MS Systems Management Server Resource Guide Contributors

Technical Writers:

Tami Beutel, Steve Kahn, Bill Muse, Candy Paape, Tim Toyoshima

Technical Consultants:

Bruce Copeland, Doyle Cronk, Mike Davis, Ben Gamble, Rick Hantz, Jennifer Harrison, Anat Kerry, Wally Mead, Oscar Newkerk, Yvette O'Meally, Roger Padvorac, Ken Pan, Michael Poling, Louise Rudnicki, Luis Salazar, Rob Wickham, David Wohlferd, Jeff Young

Technical Editor:

Marian Ranum

Production:

David Oxley, Erin Pearson

Indexer:

Julie Hatley

Graphic Designers:

Flora Goldthwaite, Sue Wyble

Graphic Artist:

Johnni Cutler


MS Systems Management Server Resource Guide

Introduction

Welcome to the Microsoft® Systems Management Server Resource Guide. This guide is designed for people who are, or who want to become, expert users of Microsoft Systems Management Server (SMS). The Microsoft Systems Management Server Resource Guide is a technical supplement to the documentation included as part of the SMS product and does not replace that information as the source for learning how to use SMS.

This guide is included in the Microsoft BackOffice™ Resource Kit. The Microsoft BackOffice Resource Kit also includes many tools that you can use to support your SMS implementation. For more information about the SMS tools, see the SMSTOOLS.HLP file on the Microsoft BackOffice Resource Kit compact disc.


About the Resource Guide

This guide includes the following chapters.

Chapter 1, "Server Reference" Describes the different types of servers used in SMS, and the components, shares, directories, and files used on those servers.

Chapter 2, "Client Reference" Describes the components used on SMS clients, and the files installed on the clients.

Chapter 3, "System Flow" Describes in detail how SMS performs its primary functions. Includes detailed system flow diagrams that illustrate how the components interact.

Chapter 4, "File Formats" Describes the text-based files that SMS uses to maintain system performance.

Chapter 5, "Working with Systems Management Server" Describes a variety of tips for working with SMS. Includes information on working with package definition files (PDFs), Network Monitor, and SNMP traps.

Chapter 6, "Tuning" Describes how to find and fix bottlenecks in an SMS system.

Chapter 7, "Troubleshooting" Provides information about troubleshooting an SMS system.

This guide also includes a glossary and an index.


Conventions in the Resource Guide

The following table summarizes the typographic conventions used in this book.

Convention | Description
bold | Command-line commands, options, and portions of syntax that must be typed exactly as shown.
italic | Information you provide, terms that are being introduced, and book titles.
KEY+KEY | Key combinations in which you press and hold down one key and then press another.
Monospace | Examples, sample command lines, program code, and program output.
SMALL CAPITALS | Names of keys on the keyboard.


Where to Look for More Information

You can find additional information about SMS version 1.2 product documentation and on the SMS Web sites, described in the following sections.


SMS version 1.2 Product Documentation

SMS version 1.2 ships with the following four books:

Getting Started

This book presents the basic information needed for new users to evaluate and quickly become familiar with the main features of SMS.

Concepts and Planning

This book describes the components that make up the product, and provides information on how to design and plan a successful implementation of SMS. This book is essential reading when you come to fully deploy SMS across your organization.

Installation and Configuration

This book explains the SMS installation options, how to create an SMS site hierarchy, and how to configure this infrastructure.

Administrator's Guide

This book provides detailed information on how to use all of the SMS features, and provides a glossary of SMS terms.

All four books are provided online. Getting Started is also included as a printed book with the SMS product. All four books can be ordered in print form by contacting Microsoft and ordering the "SMS 1.2 EN Doc Set" (SKU 271-00100).


SMS Web Sites

Visit the following Web sites for up-to-date information about SMS:

http://www.microsoft.com/smsmgmt

The SMS Web site contains up-to-date information about SMS, and links to other Microsoft BackOffice™ products.

http://www.microsoft.com/support/products/backoffice/sms.htm

The SMS Technical Support Web site gives you access to the SMS knowledge base, support information, and frequently-asked questions.

http://www.microsoft.com/TechNet/

The Microsoft TechNet Web site contains information about subscribing to the Microsoft TechNet, which provides in-depth technical information about Microsoft's business products, including SMS and other Microsoft BackOffice products.

http://www.microsoft.com/train_cert/

The Microsoft Training and Certification Web site provides information about training options and the Microsoft Certified Professional Program.


Chapter 1 - Server Reference

This chapter describes the components, directories, and shares that are installed for the Microsoft® Systems Management Server (SMS) system.


Site Server

SMS has individual components and services that maintain the system at the site level. The SMS site components are the SMS services, shares, and site server directories. By default, all site-level components and directories are installed on the server for that site. All site component directories (except outboxes) must be on the site server.


Site Server Services

There are several SMS services that can use Windows NT® user accounts and passwords and can be managed through the Windows NT Control Panel. By default, the following services run on all SMS site servers:

  • Hierarchy Manager
  • Site Configuration Manager
  • Inventory Agent
  • Package Command Manager for Windows NT
  • Client Configuration Manager
  • SMS Executive

Other SMS services include Bootstrap, SNA Receiver, SNMP Trap Receiver, and Inventory Agent for OS/2. Bootstrap runs temporarily on the secondary site servers during SMS installation. The Inventory Agent for OS/2 runs on LAN Manager for OS/2 logon servers.

Hierarchy Manager

The Hierarchy Manager monitors the site database for changes to the configuration for a site or any of its subsites. If the Hierarchy Manager detects a change in a site's proposed configuration, it creates a site control file that contains all proposed configurations for a site and sends it to the site. If you make site configuration changes using the SMS Administrator, the Hierarchy Manager must be running so it can create a site control file to make changes to that site. The Hierarchy Manager exists only in primary sites.

If changes are proposed at the primary site, its control file passes directly to the Site Configuration Manager for that site, to record the changes.

The Hierarchy Manager includes several commands for diagnosing and fixing sites. You can use PREINST.EXE, in the SMS\SITE.SRV\platform.BIN directory, to pass commands to the Hierarchy Manager while it is running. The syntax for PREINST.EXE is as follows:

preinst options

Where options are:

/DUMP

Writes site control images for all sites to the SMS\SITE.SRV\SITECFG.BOX directory.

/SYNCPARENT

Forces all site control images in the site database simultaneously up to the parent for the current site and all its subsites. Use this option when sites are out of synchronization due to time lags or job failures.

/DELSITE:{sitecode, parentsite}

Deletes incorrectly removed sites. Use this option if you removed a site before detaching it from its parent site. Note that the braces are required.

The sitecode parameter specifies the site to delete, and parentsite is the site code of the parent site for the site you are deleting. When you specify parentsite, it prevents unwanted deletion of a site previously relocated under a different parent site in another part of the site tree. For example, typing preinst /DELSITE:{CHL,PAR} deletes CHL only if it has a parent site of PAR. This transaction proceeds up the site hierarchy to all parent sites for the current site.

Note This instruction does not send a remove job to the target site. It merely removes the site and its SMS domains from the local site database and propagates the change up the site hierarchy.

/DEINSTALL:{sitecode}

Sends a job to remove a specific secondary site. The sitecode parameter specifies the site to remove from the site hierarchy. Note that the braces are required.

If you want to remove a secondary site from the hierarchy, you should first try to remove it using the SMS Administrator. If that fails for any reason, use this option.

/UPGRADE:{sitecode}

Selectively upgrades a specific secondary site. The sitecode parameter specifies the site to upgrade. If a global upgrade fails after specifying a system upgrade, use this option for the failed sites. Note that the curly braces are required.

Site Configuration Manager

The Site Configuration Manager monitors and controls the configuration of the site. The Site Configuration Manager uses the site configuration parameters in the site control files created by the Hierarchy Manager. If the site's configuration control file contains changes, the Site Configuration Manager implements the changes.

The Site Configuration Manager exists in both primary and secondary sites. It automatically restarts after the site server restarts, and it starts all other services.

When you add a Windows NT or LAN Manager domain to the site, the Site Configuration Manager:

  • Detects all logon servers (if appropriate) and verifies that each server is active and part of a supported network operating system for the domain.
  • Creates the SMS root directory (and shares it as SMS_SHRx) and the SMS_SHR share on the NTFS drive with the most free space on all logon servers. If no NTFS drive exists, it chooses the drive with the most available space even if it is a FAT drive.
  • Installs and starts the Inventory Agent to collect inventory for servers running Windows NT and LAN Manager. It also installs and starts the Package Command Manager on domain controllers.
  • Installs and starts the SMS Executive on helper servers.
  • In LAN Manager and Windows NT domains, when you select the Automatically Configure Workstation Logon Scripts option, the script files (SMSLS batch file and SETLS program files) are sent to the REPL$\SCRIPTS directory on the primary domain controller. If a user has an existing logon script, (text or ASCII script in a *.BAT or *.CMD file), the Site Configuration Manager adds the SMSLS command to the script. If a user has no logon script, it adds the script to the user's profile.
  • If you add a NetWare domain, the Site Configuration Manager creates an SMS directory on the volume with the most disk space. When you select the Automatically Configure Workstation Logon Scripts option, the system logon script for each logon server is modified. Once the system logon scripts are modified, the Site Configuration Manager installs the SMS client software in the SMS directory. The Maintenance Manager collects inventory information for the NetWare servers.

If you make site configuration changes using the SMS Administrator, the Site Configuration Manager must be running to implement the changes to the site.

Setting Monitoring Intervals for the Site Configuration Manager

The Site Configuration Manager uses values set in the Windows NT registry to determine how frequently to monitor parts of the site. You can modify these values directly in the Windows NT registry using the Windows NT Registry Editor. These values are located in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_SITE_CONFIG_MANAGER registry key. You can set the following values:

Logon Script Configuration Interval

The frequency (in minutes) that the Site Configuration Manager checks the logon script configuration for all SMS domains in the site. By default, the interval is 1440 minutes (24 hours). This interval is checked only during the processing of a site control file or at the start of the next watchdog cycle.

Restart After Shutdown Delay

Determines the duration (in minutes) that the Site Configuration Manager waits before restarting SMS services at a site after the site server and the SMS system have been restarted. The startup delay is five minutes. This is the length of time that the Site Configuration Manager waits before activating the first cycle. Subsequent cycles work from the watchdog interval.

Site Configuration Reporting Interval

The frequency (in minutes) that the Site Configuration Manager writes a new site control file to report its current configuration. By default, the interval is 1440 minutes (24 hours). Note that this interval is checked only during the processing of a site control file or at the start of the next watchdog cycle.

User Group Reporting Interval

The frequency (in minutes) that the Site Configuration Manager retrieves the list of user groups from all SMS domains in the site and writes a management information format (MIF) file to report the user groups to the site database. By default, the interval is 1440 minutes (24 hours). This interval is checked only during the processing of a site control file or at the start of the next watchdog cycle.

Watchdogging Interval

The frequency (in minutes) that the Site Configuration Manager checks for new SMS logon servers, stopped services or components, or if any of the preceding reporting or configuration intervals are up. By default, the interval is 120 minutes (2 hours). This interval resets itself to be 24 times the service response polling interval whenever the service's response rate is changed. The response polling intervals are set by the Service Response rates for the Maintenance Manager, Site Configuration Manager, and Despooler. For more information, see SMS version 1.2 Installation and Configuration, Chapter 5.

Triggering a Specific Site Configuration Manager Task

You can trigger a specific task by sending a service control code to the Site Configuration Manager using the SMS utility program SENDCODE.EXE. The syntax for SENDCODE.EXE is as follows:

sendcode sms_site_config_manager svccode

The following table lists the values for svccode supported by the Site Configuration Manager.

Name | svccode | Description
Memtrack_on | 128 | Starts memory allocation tracking.
Memtrack_off | 129 | Stops memory allocation tracking.
Memtrack_dump | 130 | Dumps the memory allocation data to ALERTER.MEM, APPMGR.MEM, HMAN.MEM, SCMANMEM.LOG, SCHED.MEM, and SMSEXEC.MEM in the root directory.
"Net pause" toggle | 132 | Toggles the net pause support on and off for the Site Configuration Manager.
Watchdog | 192 | Initiates a normal watchdog cycle (verifies current installation, checks for new SMS logon servers, restarts any stopped components, and so on).
Status | 193 | Initiates a watchdog cycle then writes a status file (.CT2).
Upgrade | 194 | Initiates a watchdog cycle but treats it as an upgrade. To be most effective, this should be preceded by shutdown.
Usergroups | 195 | Initiates a watchdog cycle and writes a user group MIF file.
Scripts | 196 | Initiates a watchdog cycle and modifies logon scripts only if the Automatically Configure Workstation Logon Scripts and the Use All Detected Servers options are enabled.
Shutdown | 234 | Stops and removes services in the site (on the site server and all SMS logon and helper servers).
Deinstall | 255 | Initiates a site removal (this removes all components, as well as files and shares, from the site server and all SMS logon and helper servers).

Inventory Agent

The Inventory Agent runs on OS/2 and Windows NT-based servers. The Inventory Agent performs software and hardware inventory on the server, except NetWare servers (Maintenance Manager performs inventory on NetWare logon servers).

The Inventory Agent is started by the Site Configuration Manager during SMS installation on domain controllers for domains which SMS controls. The Inventory Agent wakes up at an interval specified by the Inventory Agent Service Interval in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_MAINTENANCE_MANAGER registry key. The default wake-up interval is 24 hours (1440 minutes). When it wakes up, the Inventory Agent checks software and hardware scan interval settings from the local DOMAIN.INI file. By default, scan interval settings for both hardware and software are 7 (days), indicating that inventory should once every seven days. To change the software and hardware scan interval settings, use the Site Properties dialog box in the SMS Administrator.

Package Command Manager for Windows NT

The Package Command Manager is installed on all Windows NT-based servers (site and SMS logon servers) in an SMS hierarchy. The Package Command Manager service (PCMSVC32.EXE) provides unattended package installation — a user does not have to be logged on to a server running Windows NT for package installation to occur. However, the package must be configured for automated installation in background mode.

If a package arrives at a server running Windows NT that is also running the Package Command Manager (PCMWIN32.EXE file), the package is handled by the Package Command Manager.

The Package Command Manager initially wakes up once every 60 seconds to check the package polling interval. You set the polling interval in the Site Properties dialog box (under Clients) in the SMS Administrator. The default is 60 minutes. If the polling interval has elapsed, the Package Command Manager checks the package instruction file to see if the time and date have changed. If the polling interval has changed, the Package Command Manager resets the polling interval counter to the new value, and waits until that many minutes have passed before polling again. The Package Command Manager Service is limited to package installations that do not require user input and do not display windows on the server. The polling interval is set in the SMS.INI file.

Bootstrap

The Bootstrap sets up a Windows NT-based server as a secondary site. After the Hierarchy Manager at the primary site detects the request to add a secondary site, it initiates a job to the site to install the SMS installation directory on the secondary site server. It also tells the senders (LAN or RAS) to install and start the Bootstrap from that directory.

When the primary site sends a package containing site components to the secondary site, the Bootstrap:

  • Decompresses the package.
  • Creates the site directory structure, and then places components in the appropriate directories on the site server.
  • Starts the Site Configuration Manager when it detects the site control file sent by the primary site. The Site Configuration Manager then removes the Bootstrap.

SNA Receiver

After you add an SNA Sender to a site using the SMS Administrator, the SNA Receiver is activated by the Site Configuration Manager (the SNA Sender is started as part of the SMS Executive). The SNA Receiver processes information that has been sent from an SNA Sender at a remote site.

Client Configuration Manager

The Client Configuration Manager exists in both primary and secondary sites and is used by SMS Client Setup to install, upgrade, and remove SMS service components on computers running Windows NT. When SMS Client Setup needs to perform actions that may require special access on a computer running Windows NT, it posts a client configuration request to the Client Configuration Manager. The Client Configuration Manager then carries out the request. The Client Configuration Manager runs on all SMS logon servers running Windows NT Server.

The Client Configuration Manager configures the following components on Windows NT-based computers running as SMS clients:

  • SMS Client Inventory Service
  • SMS Remote Control Agent
  • SNMP Event to Trap Translator

Note

The Client Configuration Manager uses the SMS Service Account to install these components on computers running the Windows NT operating system. The service account must have administrative privileges on the computers or Client Configuration Manager will not be able to install the components. To grant administrative privileges on clients running Windows NT, do one of the following:

  • Make the SMS Service Account on the site server a member of the client's Administrators local group (directly or through other groups).
  • Have a local account on the client with the same name and password as the SMS Service Account. This account must have administrative privileges.
  • In the SMS domain where the client is a member, have an account with same name and password as the SMS Service Account.
Setting Parameters for the Client Configuration Manager

The following Client Configuration Manager parameters are maintained in the site server registry, in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_CLIENT_CONFIG_MANAGER registry key.

Deinstall All Client Services

When this value is set to Yes, it specifies that each client configuration request (CCR) be treated as a request to remove all of the SMS service-based client components. The default value is No.

Prompt for Restart

When this value is set to 0, the Client Monitor does not prompt the user at the client to restart the computer after installing software. The default value is 1, and it is not recommended that you change this value.

Ignore These Event IDs

Values specified in this parameter represent SMS event IDs that should not be reported to the Windows NT Event Manager. You can specify the following values:

402

Event that occurs when the Client Configuration Manager is unable to connect to a client. This event occurs when the SMS service account does not have administrative rights on the client, and when the client cannot be found (because it is turned off for more than seven consecutive days, it no longer exists, or its computer name has changed).

403

Event that occurs when the Client Configuration Manager succeeded in connecting to the client but encountered an error while attempting to install the client components.

When you encounter many of these events, increase the Error Reporting Delay and Retry Duration values in the site server registry (under the Retry queue) to allow the Client Configuration Manager to retry the client for longer than the default 24 hours before reporting the problem.

404

Event that appears when an excessive number of CCRs (as defined by the Machine Count Warning key in the Retry queue) appear in either the incoming or retry queues on each logon server. This event appears the first time the queue rises above the threshold number of events, and when the number of CCRs drops back below the threshold numbers.

These events indicate a backlog of clients to process. If you see an event for the incoming queue, the Client Configuration Managers running on the logon servers are not keeping up with the demand, and you need to consider performance and tuning issues for the site.

Only Report These Event IDs When Fatal

Values specified in this parameter represent SMS event IDs that should be reported to the Windows NT Event Manager only after they are "fatal," which means that the Client Configuration has stopped retrying to connect to the client and install or maintain client components. This value can be 402 or 403.

SNMP Trap Receiver

The SNMP Trap Receiver makes simple network management protocol (SNMP) trap information available to SMS. The SNMP Trap Receiver is disabled (no traps are received by or stored in the database) by default. You configure the SNMP Trap Receiver using the Site Properties dialog box (under SNMP Traps) in the SMS Administrator.

The SNMP Trap Receiver filters traps according to conditions you set. You can set trap filters based on the trap IP address, enterprise ID, Windows NT event source (for traps generated by the Event to Trap Translator), generic trap type, or specific trap ID. Filtered traps are either written to the database or discarded.

If a trap meets the filter conditions, SMS writes the trap data to the database. However, to minimize the impact on the database, SMS only writes the first 25 varbinds in the trap to the database. SMS also limits the size of each varbind. If any of the varbinds exceed the limit, SMS rejects the trap data. The data is not written to the database; a Windows NT event is created to log the failure instead.

The SNMP Trap Receiver can receive traps from any suitable SNMP source, including (but not limited to) the Event to Trap Translator. Traps generated by the Event to Trap Translator display the Windows NT event source name for the event that triggered the trap.

The SNMP Trap Receiver runs at all primary sites. It stores SNMP trap data in the database as a new architecture. This means that trap data can be viewed, queried against, and used to generate SMS alerts.

SMS Executive

The SMS Executive serves as a master controller of several SMS components. The SMS Executive is started by the Site Configuration Manager, during SMS services startup and any other time that the SMS Executive is not running.

The SMS Executive reads the Windows NT registry to determine which components to start on SMS site, logon, and helper servers. By default, it starts the following components on the site server:

  • Maintenance Manager
  • Inventory Processor
  • Site Reporter
  • Scheduler
  • Despooler
  • Inventory Data Loader
  • Senders
  • Applications Manager
  • Alerter

Each of these components is discussed in the following sections.

Maintenance Manager

The Maintenance Manager installs and maintains the SMS client components on the SMS logon servers in a site. It replicates client components and configuration information to SMS logon servers within the site and retrieves inventory and status files. The Maintenance Manager is installed in every primary and secondary site server. The Site Configuration Manager sets up the registry information and necessary directory structures that the Maintenance Manager needs to run properly.

When a logon server is added to the SMS system, the Maintenance Manager replicates client files, such as the Inventory Agent, Program Group Control, and Package Command Manager programs, to the logon server. The Maintenance Manager also monitors the site server for any changes in configuration. If a change is detected, the Maintenance Manager replicates these changes to all of the SMS logon servers within the site. The Maintenance Manager also periodically scans all the logon servers and updates missing files.

In addition, the Maintenance Manager:

  • Monitors the package rule file for changes and replicates it as necessary.
  • Passes files back and forth between the site server and SMS logon servers according to the polling interval. For example, it moves RAW files from each SMS logon server to the site server and replicates Package Command Manager instruction files and SMS network applications from the site server to all SMS logon servers.
  • Collects inventory from NetWare servers and creates a corresponding MIF file.
  • Reads the SYSTEM.MAP file and creates copy lists for the SMS Client Setup program. A copy list tells SMS Client Setup where to place files on the client.
  • Creates the unique identifier (*.UID) file. The *.UID file name prefix represents the next available SMS ID number for an SMS logon server.
  • Detects when the Despooler has distributed the package, then creates and sends package location MIF files.
Inventory Processor

The Inventory Processor exists in both primary and secondary site servers. It creates the MIF files from the raw binary inventory information returned by the Inventory Agents for Windows NT and MS-DOS® and reads the MIF files returned by the Inventory Agents for OS/2 and Macintosh clients. The Inventory Processor creates a history file for the Windows NT, Apple Macintosh, and OS/2 platforms. MIF files also track history, unless they are created with an NHM extension. When a new MIF file is received, the Inventory Processor compares it with the history file and writes changes to an inventory file called a Binary MIF file. (If this is the first MIF file, the Inventory Processor writes a complete Binary MIF inventory file.)

The Inventory Processor also converts MIF files in the ISVMIF directory into Binary MIF files. ISVMIFs are files generated by independent software vendors (ISVs), which report objects such as computers that have custom architectures. The ISVMIF directory also contains MIF files from OS/2 and Macintosh clients.

Site Reporter

The Site Reporter maintains a queue of MIF files containing inventory, job status, or event information. At child sites, the Site Reporter periodically creates a system job to send these files to the parent site. The queue length that triggers when the files are sent is determined by various registry settings. The Site Reporter keeps track of the different categories of MIF files that arrive for it and compares the category with a registry entry that indicates how long that type of MIF file should be allowed to wait. When any MIF file reaches its maximum wait time, all MIF files for that site are bundled and sent. The registry entries for the Site Reporter are under the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_SITE_REPORTER key and are maintained by the Site Configuration Manager.

The Site Reporter also deletes MIF files that are not reported to parent sites, either because there is no parent site or because the MIF file is normally not reported to a parent site (such as a job detail MIF file).

The Site Reporter exists in both primary and secondary sites.

Scheduler

The Scheduler detects pending jobs and creates auxiliary files that enable jobs to be processed. This includes jobs that an administrator starts, such as a Run Command On Workstation job, as well as system jobs from system processes such as the Site Reporter.

When the Scheduler detects a job, it:

  • Compresses the relevant files (such as all files in a package source directory or all inventory MIF files) into a single file.
  • Creates a despooler file, in the SMS\LOGON.SRV\DESPOOLER.BOX directory, with instructions for completing the job at the receiving site.
  • Creates a send request file (*.SRQ) with instructions for sending the compressed files and the despooler instructions to the target site, in the corresponding sender outbox.

The Scheduler also manages send requests. It examines send requests for a specific sender's outbox and schedules them on a priority basis. For example, it might suspend a low priority job in progress and substitute a higher priority send request. After the higher priority job runs, it restarts the previous job.

The Scheduler runs on the site server, but you can use the Services button in the Site Properties dialog box in the SMS Administrator to move it to a helper server. The Scheduler exists in both primary and secondary sites.

Despooler

The Despooler watches the SITE.SRV\DESPOOLR.BOX\RECEIVE directory for despooler instruction files and compressed packages created by the Scheduler. The instructions and packages can come from the local site or from another site. The Despooler reads the instruction file and uses the instructions to decompress the package files and determine how to process them. For example, it decompresses inventory files and moves them to the SMS\SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory so they can be processed by the Inventory Data Loader, which then updates the site database.

Note

Specify the drive that the Despooler will use for temporary files in the Preferred Drive For Temp Directory setting for the Despooler registry key. This value is blank by default, which directs SMS to use its drive. The SMS Drive Minimum Free Space in Mbytes option specifies that SMS look for a drive of the configured value (default value is 100 MB). If the free disk space on the SMS drive is less than 100 MB, the Despooler will start looking for other drives on which to place the package.

If there are two package shares, the Despooler will pick the drive (share) with the most free disk space until both of them have less than 100 MB of free space. Then it attempts to find a third drive with more free disk space. The Despooler will never place the same package on two shares even if they came in different jobs. To determine where packages are stored, look under the SMS\Components\SMS_Despooler\Transfer Package registry key.

For Run Command On Workstation jobs, the Despooler updates the Package Command Manager instruction files for all target computers in the site. After the package has been installed, the Despooler reports the job's status to the site where the job was created. It also logs an event to the site server's Windows NT event log if there is a failure.

The Despooler initially runs on the site server but can be moved to a helper server. The Despooler exists in both primary and secondary sites.

Inventory Data Loader

The Inventory Data Loader updates computer inventory, events, job location, and user group and job status information in the database. When an inventory MIF file arrives from a computer, the Inventory Data Loader attempts to locate the computer in the site database based on its SMS ID and key attributes in its identification group. If the MIF file contains instructions to update an object, such as a client's identification group that is missing from the database, the Inventory Data Loader initiates a resync command to update the database. The Inventory Data Loader processes job status, user group, event, and package location information, and then updates the database directly (no resync is necessary).

In SMS version 1.2, each of the main architectures creates MIF files with different extensions, as shown in the following table:

MIF file name extension | Contains
.EMF | Event data
.JMF | Job status data
.UMF | User group data
.PMF | Package location data

All other MIF files are processed by the 'misc' processing thread, including MIF files from sites that are running earlier versions of SMS. The Inventory Data Loader processes the different MIF files in parallel.

The Inventory Data Loader:

  • Monitors the DELTAMIF.COL directory for MIF files.
  • When it finds a file, it moves the file to the DELTAMIF.COL\PROCESS directory.
  • Starts the appropriate thread to process the file.
  • Copies the file to the SITEREF.BOX directory.

Note

If the Inventory Data Loader is stopped before it has finished processing a MIF file, that file is renamed with an X at the beginning of the file name (for example, X0712.EMF). When the file has three X's at the beginning of the file name, it is considered a corrupt MIF file and is moved to the DELTAMIF.COL\BADMIFS directory.

If you stop and restart SMS Executive often, you might end up with many files in the DELTAMIF.COL\BADMIFS directory that would otherwise process normally.

The Inventory Data Loader is also responsible for:

  • Transferring the inventory from a child site to the Site Reporter, which uses a sender to deliver the information to a parent site after the parent/child hierarchy is first established.
  • Forwarding Binary MIF files to the Site Reporter after processing them. The Site Reporter creates a job to send Binary MIF files to a parent site if it exists.

The Inventory Data Loader initially runs on the site server but can be moved to a helper server. The Inventory Data Loader exists only in primary sites.

Senders

To enable each site to communicate with its parent sites and child sites, every site must have one or more senders. A sender is an SMS component used to transmit instructions and data from one site to another (such as reporting inventory information or installing software on clients in another site).

There are six types of SMS senders:

  • One LAN Sender
  • Three RAS Senders (ISDN, X.25, and ASYNC)
  • Two SNA Senders (batch and interactive)

Each type of sender uses a specific type of communications link. The RAS Senders require a Remote Access Service (RAS) server, and the SNA Senders require the SNA Server communications service.

The sender monitors its outbox directory (the location for files waiting to be sent to another site) for a valid send request. When it detects a valid request, the sender connects to the target site and transfers the compressed files and its despooler instruction file to the destination site.

The LAN Sender runs on the site server but can be moved to a helper server. Use the SMS Administrator to add other senders. The sender exists in both primary and secondary sites.

Applications Manager

The Applications Manager copies package and program group configuration information from the site database to other components in the site and to the sites beneath it in the site hierarchy.

When you create, modify, or delete packages or program groups using the SMS Administrator, the changes are added to the site database. When the Applications Manager detects a change to a package or program group, the new configuration information is updated in the Program Group Control database for the site. The Program Group Control database is a set of configuration files used by the Applications Control program for each SMS Windows®-based client.

The Applications Manager uses a system job to replicate package and program group data to child sites. Each child site then generates its own copy of the Program Group Control database. The Applications Manager also uses a system job to add data to the database from parent sites.

The Applications Manager exists in both primary and secondary sites.

Alerter

The Alerter monitors the database for new alerts and any changes to existing alerts. It runs queries associated with alerts and compares query results with alert criteria.

If an alert's trigger condition becomes true, the Alerter performs any or all of the following actions:

  • Logs an SMS event and a Windows NT event.
  • Runs a command line from the system path of the computer where the Alerter is installed.

Note

The Alerter cannot run a command that writes to a window.

  • Sends a message to a computer or user on the local network.

The Alerter exists only in primary sites.


SMS Services Memory Requirements

SMS services require approximately 19 MB of memory on primary site servers. The following tables lists the service or service thread RAM requirements.

SMS service or service thread | Memory requirement
APPCTL32 | 999 K
CLICFG | 623 K
INVWIN32 | 602 K
PCMSVC32 | 500 K
PCMWIN32 | 549 K
PREINST (primary site only) | 1,466 K
SITEINS | 1,671 K
SMS | 2,625 K
SMSEXEC | 2,338 K
Subtotal | 11,373 K
Overhead | 7,336 K (5,012 K on SMS logon servers)
Total for primary site | 18,709 K


Site Server Shares

During installation, the Site Configuration Manager creates the shares shown in the following table.

Share name | Used by | Description
SMS_SHRx | SMS services | Represents the SMS root directory, where x is the drive where SMS is installed. It exists on all site, logon, and helper servers running Windows NT or LAN Manager.
SMS_SHR | Inventory Agent, SMS Client Setup, Program Group Control, Package Command Manager, and MIF Entry | Created on the site server and all SMS logon servers running Windows NT or LAN Manager. It represents the LOGON.SRV directory, which is a subdirectory of the SMS root directory. This share contains all SMS logon server components and serves as the collection point for inventory files.
SMS_SITE | Bootstrap, Despooler, and sender | Exists only on site servers. It represents the SMS\SITE.SRV\DESPOOLR.BOX\RECEIVE directory and is the location where remote site senders place despooler instruction files and compressed packages that are targeted for the site.

Important

Do not modify share comments! These are read by services and will cause errors if they are altered.


Site Server Directories

When you set up a site, directories are created on the site server (for a primary or secondary site). For primary sites, the drive and SMS root directory name are the ones specified when you created the site using the SMS Setup program. For secondary sites, the drive and the SMS root directory name are the ones you specified when you created the site using the SMS Administrator.

In general, the directory names follow this naming scheme:

  • The first level directory name (such as SITE.SRV and LOGON.SRV) indicates the server's role and contains the directories for those components. For example, the site components use SITE.SRV directories.
  • The second level directories (such as DESPOOLR.BOX) are named for the components that monitor or use the directory. For example, the Despooler monitors the DESPOOLR.BOX\RECEIVE directory for new packages and instructions from other sites.
  • The third level directories normally contain specific types of files. For example, the MAINCFG.BOX\PKGRULE directory contains the master copy of the package rules used for software inventory at the site.

A site server contains the following directories:

drive:\SMSroot
    LOGS
    SITE.SRV
        APPMGR.BOX
        DATALOAD.BOX
            DELTAMIF.COL
                BADMIFS
                PROCESS
            FILES.COL
        DESPOOLR.BOX
            RECEIVE
            STORE
        INVENTRY.BOX
            BADRAWS
            HISTORY
        ISVMIF.BOX
        MAINCFG.BOX
            APPCTL.SRC
                DATABASE
                INIFILES
                SCRIPTS
            CLIENT.SRC
                platform.BIN
                    language
            INVDOM.BOX
                domainname.000
            MSTEST
                platform.BIN
                    language
            PCMDOM.BOX
                domainname.000
            PKGRULE
        SCHEDULE.BOX
        SENDER.BOX
            TOSEND
            REQUESTS
        SITECFG.BOX
        SITEREP.BOX
        platform.BIN
            language
            ERRORHIS

A primary site also contains the following directories, which provide the sample scripts (for package installation and SMS network application configuration) and secondary site configuration information:

drive:\SMSroot
    PRIMSITE.SRV
        AUDIT
            PACKAGE
                platform.BIN
                    language
        IMPORT.SRC
            language
        RMOTECFG.BOX
        RMOTESRC.BOX

Both site and SMS logon servers also contain the following directories for desktop services such as the Package Command Manager and the Inventory Agent for Windows NT:

drive:\SMSroot
    HELPER.SRV
        platform.BIN
            language
            ERRORHIS

If an SMS component, such as the Scheduler, is moved to an SMS logon server to reduce site server load, the files required to run the component are also placed in the HELPER.SRV directory. For more information about the SMS logon server directories, see "SMS Logon Server Directories" later in this chapter. The site server directories are described in the following table.

Directory

Description

SITE.SRV

Contains the site server directories.

APPMGR.BOX

The location for secondary sites where the Applications Manager stores package and program group information.

DATALOAD.BOX

Stores decompressed inventory files.

…\DELTAMIF.COL

The location at primary sites where the job status MIF files (*.JMF) are placed.

The Inventory Data Loader monitors this directory and uses the job status MIF file to update the site's database (if the site is a primary site) and then forwards the job status MIF file to its parent site.

…\…\BADMIFS

Contains MIF files that could not be processed by the Inventory Data Loader.

…\…\PROCESS

Contains MIF files that the Inventory Data Loader recognized and has started to process.

…\FILES.COL

Contains collected files for the current site and all subsites.

DESPOOLR.BOX

Contains Package Command Manager job status MIF files, placed by the Maintenance Manager, for the Despooler to examine.

…\RECEIVE

The location where the sender places despooler instruction files and compressed packages that are targeted for the site.

The Despooler monitors this directory and processes any instruction files found.

…\STORE

The location where the Despooler stores compressed packages sent to the site from its own site or another site.

INVENTRY.BOX

The location where Maintenance Manager puts client inventory files (*.RAW files) that it collects from SMS logon servers. The Inventory Processor monitors this directory.

…\BADRAWS

Contains client inventory files (*.RAW) that could not be processed by the Inventory Processor.

…\HISTORY

The location where the Inventory Processor maintains a record (history) of the last inventory for each SMS client.

ISVMIF.BOX

Contains MIF files generated by ISVs.

MAINCFG.BOX

Contains SMS directories used by the Applications Manager and the Maintenance Manager.

…\APPCTL.SRC

Contains directories used by the Application Control program for SMS network applications.

…\…\DATABASE

The location where the Applications Manager places the network application database for SMS network applications at the site.

The Maintenance Manager replicates these files to the SMS\LOGON.SRV\APPCTL.BOX directory for each SMS logon server for every SMS domain in the site.

…\…\INIFILES

The location of initialization files for SMS network applications at the site.

…\…\SCRIPTS

The location of script files for SMS network applications at the site.

…\CLIENT.SRC

The location where the SMS client components are placed as source for configuration and replication to the site's logon servers.

The Maintenance Manager uses this directory to generate configuration files for SMS Client Setup and the Inventory Agent service on each SMS logon server. The configuration files and the SMS client components are replicated to the SMS\LOGON.SRV\platform.BIN directory on each SMS logon server for every SMS domain in the site.

…\INVDOM.BOX

The location of the master inventory command file (RESYNC.CFG) for each SMS domain. The Maintenance Manager replicates RESYNC.CFG to the SMS\LOGON.SRV directory for each SMS logon server for every SMS domain in the site.

MSTEST

The location where the run-time version of Microsoft Test is placed as a source for replication to the site's logon servers. The directory also contains utilities used in the operating system installation jobs.

The Maintenance Manager replicates these files to the SMS\LOGON.SRV\MSTEST directory for each SMS logon server for every SMS domain in the site.

PCMDOM.BOX

The location where the Despooler places instructions for target clients of Run Command On Workstation jobs in each SMS domain.

The Maintenance Manager replicates the instruction files to the SMS logon servers in the SMS domains that contain the target clients.

…\PKGRULE

The location where the Applications Manager places the PACKAGE.RUL file, which contain rules for inventorying packages at the site.

The Maintenance Manager uses the PACKAGE.RUL file to generate the configuration file for the Inventory Agent. This configuration file (PKG_16.CFG) is replicated to the SMS\LOGON.SRV directory on each SMS logon server for every SMS domain in the site.

SCHEDULE.BOX

The location where SMS services can leave instructions for system jobs.

The Scheduler monitors this directory and uses the instructions to start the specified system jobs.

SENDER.BOX

The location where all senders installed in a site are stored.

…\TOSEND

The location where the Scheduler places compressed packages and despooler instruction files to be sent to target sites.

When the sender processes a send request for a job, it sends the job's files from this directory to the target site.

REQUESTS

The location where the Scheduler places send request files for the sender. The specific sender assigned to each subdirectory (outbox) monitors its directory and processes the requests.

SITECFG.BOX

The location where SMS places site control files used by the Site Configuration Manager to configure the site.

SITEREP.BOX

The location at secondary sites where the job status MIF files (*.JMF) are placed.

When the Site Reporter detects a queue of job status MIF files, it creates a system job that sends these MIF files to the parent site.

…\platform.BIN

The location where all the SMS server components (the SMS Administrator, services, and dynamic-link libraries [DLLs]) are installed. This directory appears as X86.BIN on Intel-based systems, as ALPHA.BIN on Alpha-based systems, and as MIPS.BIN on MIPS-based systems. By default, this is the location for the Package Command Manager and Inventory Agent service executables.

This directory contains a language ID subdirectory (for example, 00000409 for English), which contains language specific files. The name used is the Win32® locale identifier.

…\ERRORHIS

The location where SMS components write event history files to prevent frequently occurring events from flooding the Windows NT event log and the SMS event log in the SMS database.

PRIMSITE.SRV

Contains directories installed on and used by primary sites.

…\AUDIT

The location of inventory code for the Software Audit program that runs as a Package Command Manager job.

…\…\PACKAGE

The location of inventory code for software inventory.

…\IMPORT.SRC

The location of the sample configuration scripts provided with SMS.

…\…\Language

The location of the supplied package definition files (PDFs). For example, when you install U.S. English, the PDFs are located in this directory: PRIMSITE.SRV\IMPORT.SRC\ENU

…\RMOTECFG.BOX

The location where the Site Hierarchy Manager puts packages containing site control files for secondary sites.

…\RMOTESRC.BOX

The location that the Site Hierarchy Manager uses to build a complete directory tree when a job is sent to install a secondary site.

HELPER.SRV

Contains directories associated with desktop services (Inventory Agent, Package Command Manager) installed on all SMS servers. The files that are required to run components that have been moved from the site server are also placed here.

Note

The location of the PDFs has changed from version 1.0 of SMS. These files were directly under the IMPORT.SRC directory. Now, they are in a language-specific subdirectory under the IMPORT.SRC directory. If you upgrade from version 1.0, the new directories will be added to the old directory structure, but will not overwrite custom changes made in the IMPORT.SRC directory. You should move any files you need from IMPORT.SRC to the appropriate language subdirectory, and then delete the duplicate files in IMPORT.SRC. The PDF files have changed, so be sure to use the new PDF files when you import packages.

Network Monitor Directories

If you install Network Monitor with SMS Setup, the SMS site server will contain the following directories:

drive:\SMSroot
    NETMON
        platform
            CAPTURES
            PARSERS

These directories are described in the following table.

Directory | Description
platform | Contains initialization files, help files, and the NMAPI.DLL, which defines the Network Monitor API.
…\CAPTURES | The location of the default filters that accompany Network Monitor (DEFAULT.CF, DEFAULT.DF, NOBROAD.CF, and NOBROAD.DF).
…\PARSERS | The location of Network Monitor protocol parsers. These parsers are DLLs that distinguish one protocol from another and copy frames to the Network Monitor capture buffer. To capture frames sent in a particular protocol, a corresponding parser must exist in this directory and must be enabled. In addition, this directory contains SMB.HLP, an online version of the Server Message Block (SMB) Protocol specification.


Site Server Default Permissions

The following table lists the default permissions for shares and directories on SMS site servers. For a description of Windows NT file and special permissions, see your Windows NT documentation.

Share | Directory | Permissions
SMS_SHRx |  | Administrator's local group has full control; Everyone has Read capabilities.
 | SMSroot | Administrator's local group has full control; Everyone has Read capabilities.
 | SITE.SRV and all subdirectories | Administrator's local group has full control.
 | HELPER.SRV and all subdirectories | Administrator's local group has full control.
 | LOGS | Inherits permissions from the drive where SMS is installed. Defaults to Everyone has full control.
 | PRIMSITE.SRV and all subdirectories | Inherits permissions from the drive where SMS is installed.
 | NETMON and all subdirectories | Inherits permissions from the drive where SMS is installed.
SMS_SHR |  | Administrator's local group and Everyone have full control.
 | (Windows NT and LAN Manager) | Administrator's local group has full control; Everyone has Read capabilities.
 | DESPOOLER.BOX INVENTRY.BOX ISVMIF.BOX PCMPKG.SRC SMSID\*.UID (file) | Administrator's local group has full control; Everyone has Change capabilities.
 | platform.BIN platform.BIN\language | Administrator's local group has full control; Everyone has Read capabilities.
 | MSTEST PCMINS.BOX INVENCFG.BOX APPCTL.SRC and all subdirectories | Administrator's local group has full control; Everyone has Read capabilities.
 | PCMPKG.SRC\packageID CCR.BOX | Administrator's local group has full control; Everyone has Change capabilities. (Read and Write permissions for Users and Guests can be modified through the user interface. By default, Users and Guests have Read and Write permissions.)


SMS Logon Servers

Every site has one or more SMS domains and each domain has at least one SMS logon server. From the site server, the following SMS components maintain SMS on every SMS logon server in an SMS-supported domain:

  • Site Configuration Manager
  • Maintenance Manager
  • Despooler

If you move an SMS component from the site server to another SMS logon server, you create an SMS helper server. This configuration reduces the load on site servers.

Helper servers must be logon servers running Windows NT that are in one of the site's domains, and the HELPER.SRV directory must be on an NTFS partition. If the SMS domain containing a helper server is configured with the Use Specified Servers option in the Domains dialog box (under Site Properties), the helper server must be one of these servers. You can allow an unlimited number of helper servers.

When you move a component to another server, files required to run the specific SMS components are placed in the server's HELPER.SRV\platform.BIN directory. The Site Configuration Manager creates the SMS_SHRx share on that drive and copies the required component files to the HELPER.SRV\platform.BIN directory.

SMS_SHRx also contains desktop services (the Package Command Manager and Inventory Agent), which are automatically installed on all SMS logon servers by the Site Configuration Manager.


SMS Logon Server Shares

During installation, the Site Configuration Manager creates the SMS_SHRx and SMS_SHR shares. SMS logon servers also use a NETLOGON share. The SMS logon server shares are described in the following table.

Share name | Used by | Description
SMS_SHRx | SMS services | Represents the SMS root directory where x is the drive on which SMS is installed. It exists on all site, SMS logon, and helper servers running Windows NT or LAN Manager.
SMS_SHR | Inventory Agent, SMS Client Setup, Program Group Control, Package Command Manager, and MIF Entry | Created on the site server and all SMS logon servers running Windows NT or LAN Manager. It represents the LOGON.SRV directory, which is a subdirectory of the SMS root directory. SMS_SHR contains all SMS logon server components and serves as the collection point for inventory files.
NETLOGON | SMS logon servers | If you enable the Automatically Configure Workstation Logon Scripts option, the Site Configuration Manager automatically copies the files needed to use the SMSLS batch file as a logon script to the REPL$ share on servers running Windows NT or LAN Manager. These files are then replicated to the NETLOGON share of domain logon servers by the LAN Manager Replicator service or the Windows NT Directory Replicator service.

Important Do not modify share comments! These are read by services and will cause errors if they are altered.

Note The SMSLS.BAT file from version 1.0 has been split into two files that initiate SMS inventory and client setup. The new version of SMSLS.BAT is used for logon scripts and is located in the NETLOGON share. The old version of SMSLS.BAT will remain under SMS_SHR to allow you to copy any custom changes from that file to the new SMSLS.BAT file in the NETLOGON share. You should delete the old SMSLS.BAT file after the changes are copied. Use the new RUNSMS.BAT file when manually running from SMS_SHR. There are also two command (.CMD) files to support OS/2 clients.

The Site Configuration Manager copies the files into a domain set to enumerate all servers added to SMS. The following table lists the components required by the SMS logon script.

Component | Description
CLRLEVEL.COM | Resets the error level to 0 before the script quits.
DOSVER.COM | Verifies if the client is running an SMS-supported version of MS-DOS.
NLSMSG16.EXE | Used by clients running MS-DOS, Windows version 3.1, Windows for Workgroups, and Windows 95 as a NLS-enabled version of CHOICE.COM. It is used when user input is required.
NLSMSG32.EXE | Used by clients running Windows NT as an NLS-enabled version of CHOICE.COM. It is used when user input is required.
NLSMSGO2.EXE | Used by OS/2 clients as an NLS-enabled version of CHOICE.COM. It is used when user input is required.
NLSRES.INI | Used by NLSMSGx.EXE as a language mapping file to relate country codes or language IDs to the appropriate NLS_LS.DLL file.
NETSPEED.COM | Detects a slow network.
SMSLS.BAT | Logon script file (except for OS/2 clients).
SMSLS.CMD | Logon script file for OS/2 clients.
SETLS16.EXE | Finds SMS logon servers and launches CLI_DOS and INVDOS.
SETLS32.EXE | Used by clients running Windows NT to find SMS logon servers and launch CLI_NT and INVWIN32.
SETLSOS.EXE | Used by OS/2 clients to find SMS logon servers and launch CLI_DOS and INVOS2.
SMSLS.INI (present when domain mapping is used) | Maps clients to SMS domains.


SMS Logon Server Directories

Each logon server in a SMS domain has the following directories:

drive:\SMSroot
    LOGON.SRV
        APPCTL.BOX
            DATABASE
            INIFILES
            SCRIPTS
        CCR.BOX
            RETRY
        DESPOOLR.BOX
        INVENCFG.BOX
        INVENTRY.BOX
        ISVMIF.BOX
        MSTEST
            platform.BIN
        PCMINS.BOX
        PCMPKG.SRC
        SMSID
        platform.BIN
            language

The following table shows the SMS logon server directories.

Directory | Description
LOGON.SRV | Stores components for scanning and collecting inventory from clients. Also stores SMS client components for installation on clients running MS-DOS, Windows version 3.1, Windows for Workgroups, Windows 95, and Windows NT.
…\APPCTL.BOX\ DATABASE | The location where the Maintenance Manager places the SMS network application database.
…\CCR.BOX\RETRY | Contains client configuration files (*.CCR) that the Client Configuration Manager could not complete.
…\DESPOOLR.BOX | The location where the Package Command Manager writes a despooler instruction file (*.SNI) and application status MIF files after it has completed a package installation. The .SNI file reports status for the Run Command On Workstation job. The Maintenance Manager monitors this directory and moves instruction files to the site server.
…\INVENCFG.BOX | The location where the Maintenance Manager places resync files (*.CFG).
…\INVENTRY.BOX | The location where the Inventory Agent places client inventory files (*.RAW files) collected from clients. The Maintenance Manager monitors this directory and moves the inventory files to the SITE.SRV\INVENTRY.BOX directory on the site server.
ISVMIF.BOX | The location where the Inventory Agent puts MIF files generated by ISVs and inventory files for Macintosh and OS/2 clients. The Maintenance Manager monitors this directory and moves the MIF files to the SITE.SRV\ISVMIF.BOX directory on the site server.
…\MSTEST | The location where Maintenance Manager places the run-time version of Microsoft Test and scripting types of information. It includes common files and applications for client installations using Package Command Manager and Program Group Control and platform-specific subdirectories for X86.BIN, ALPHA.BIN, and MIPS.BIN.
…\PCMINS.BOX | The location where the Maintenance Manager replicates Package Command Manager instruction files (*.INS) from the site server. This directory is monitored by the Package Command Manager.
…\PCMPKG.SRC (NetWare servers) | The location of directories containing decompressed package source files. Each package directory name is the package ID for the package.
…\SMSID | The location of a single file (*.UID), which gives unique SMS IDs to clients that are added to the SMS domain.
…\platform.BIN\language | The location of SMS client executables for installation on clients. This directory is maintained by the Maintenance Manager.

SMSSVR16.EXE and SMSSVR32.EXE are installed on the SMS logon server for upgrading and removing SMS components. However, to start the SMS Client Setup program for upgrades or removal, the program must be run from the client.

Directory Structure for the NETLOGON Share

The directory structure for the NETLOGON share has changed since SMS version 1.0. The SCRIPTS\platform.BIN directory for each client platform has been added. The files that are included in this directory, as well as the previous location, are shown in the following table.

File name | Moved from
SETLS32.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\platform.BIN
NLSMSG32.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\platform.BIN
NLSRES.INI | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\platform.BIN
SETLS16.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\X86.BIN
NLSMSG16.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\X86.BIN
SETLSOS2.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\X86.BIN
NLSMSGO2.EXE | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\X86.BIN

The SCRIPTS\platform.BIN\language directory for each client language has been added.

File name | Moved from
NLS_LS.DLL | SITE.SRV\MAINCFG.BOX\CLIENT.SRC\platform.BIN\00000409


SMS Logon Server Default Permissions

The following table lists the default permissions for shares and directories on SMS logon servers.

Share/volume | Directory | Permissions
SMS_SHRx |  | Administrator's local group has full control; Everyone has Read capabilities.
 | SMSroot | Administrator's local group has full control; Everyone has Read capabilities.
 | HELPER.SRV and all subdirectories | Administrator's local group has full control.
 | LOGS | Inherits permissions from the drive where SMS is installed. Defaults to Everyone has full control.
NetWare volume |  | No change from existing.
 | SMS\LOGON.SRV (NetWare) | No change from existing.
SMS_SHR |  | Administrator's local group and Everyone have full control.
 | (Windows NT and LAN Manager) | Administrator's local group has full control; Everyone has Read capabilities.
 | CCR.BOX DESPOOLER.BOX INVENTRY.BOX ISVMIF.BOX PCMPKG.SRC SMSID\*.UID (file) | Administrator's local group has full control; Everyone has Change capabilities.
 | platform.BIN platform.BIN\language | Administrator's local group has full control; Everyone has Read capabilities.
 | MSTEST PCMINS.BOX INVENCFG.BOX APPCTL.SRC and all subdirectories | Administrator's local group has full control; Everyone has Read capabilities.
 | PCMPKG.SRC\packageID | Administrator's local group has full control; Everyone has Change capabilities. (Read and Write permissions for Users and Guests can be modified through the user interface. By default, Users and Guests have Read and Write permissions.)

Important

Do not modify share comments! These are read by services and will cause errors if they are altered.


Package Distribution Servers

The following table shows default permissions for SMS shares and directories on package distribution servers. For a description of Windows NT file and special permissions, see your Windows NT documentation.

Share | Directory | Permissions
Shared package share | SharedPackageDirectoryName (Windows NT and LAN Manager) | Administrator's local group and Everyone have full control.
SMS_PKGx | SharedPackageDirectoryName \OptionalDirectory (Windows NT and LAN Manager) | Administrator's local group, Everyone, and users have full control.
 | PackageID | Administrator's local group has full control; Everyone and users have Read capabilities.


Chapter 2 - Client Reference

The Microsoft Systems Management Server (SMS) system supports clients running MS-DOS and Windows version 3.1, Windows for Workgroups version 3.11, Windows 95, Windows NT version 3.51 and later, Macintosh System 7.x, OS/2 version 2.11, and OS/2 Warp. Supported protocols include NetBEUI, TCP/IP, IPX, and AppleTalk.

This chapter describes the SMS client components and programs, the client files that are modified by SMS, and provides troubleshooting tips for SMS clients.


Client Components

The first time a client is added to an SMS-supported domain, the SMS system installs and configures the SMS client components on the client, assigns the client a unique SMS ID, and scans the client to collect its inventory.

Each SMS client running Windows NT, Windows 95, Windows version 3.1, Windows for Workgroups, and MS-DOS contains the following directories.

Directory | Contains
MS\SMS\BIN | Executable files for the major SMS components.
MS\SMS\DATA | Files that provide data or input to executable files.
MS\SMS\LOGS | Log files written by SMS client components. For version 1.2, several client files have been moved from the MS\SMS\BIN directory to this directory.
MS\SMS\INVDATA | Raw inventory files that are created by the Inventory Agent.
MS\SMS\IDMIFS | Extended client inventory when an IDMIF is placed in the IDMIFS directory on an SMS client.
MS\SMS\NOIDMIFS | Inventory information that contains groups with no ID or architecture.
MS\SMS\TEMP | Files that are created for temporary use.

The following table describes the major SMS components on clients running Windows NT, Windows 95, Windows version 3.1, Windows for Workgroups, and MS-DOS (Macintosh files are listed in a table in the section "Macintosh Components" later in this chapter). For a complete list of SMS files installed on clients, see the CL_*.TXT files in the LOGON.SRV directory on an SMS logon server. There is one file for each type of client supported.

Note

If a client component has a 16-bit, a 32-bit, and a Windows 95 version, the following table lists all filenames separated by a slash (/), as in APPCTL16.EXE/APPCTL32.EXE/APPCTL95.EXE. If a file has separate NetBIOS and IPX versions, the IPX version is noted in parentheses, as in USERTSR.EXE (USERIPX.EXE).

Directory | Component | Description
drive:\SMSroot | SMS.INI | Initialization file that contains configuration information for the inventory, Package Command Manager, software auditing, and shared application components on the client. SMS.INI is generated by SMS Client Setup and is updated by several other SMS client components. It contains a unique ID used by SMS to identify the client. SMS.INI is always a hidden file in the root of the first (alphabetical) local hard drive.
Windows | _WCHAT32.DLL | Library used by WCHAT32.EXE for internationalization resources, on clients running Windows NT.
 | _WSLAV32.DLL | Library used by WSLAVE32.EXE for internationalization resources, on clients running Windows NT.
 | ACMEWKS_.DLL | Library used by the Microsoft Test program.
 | ACTDLL16.DLL/ ACTDLL32.DLL/ ACTDLL95.DLL | Library used by the Applications Control program.
 | APPSTART.EXE | Shell program that locates and runs SMS shared applications.
 | APSRES16.DLL/ APSRES32.DLL/ APSRES95.DLL | Library that contains locale/language-specific strings used by APPSTART.EXE.
 | CPPS32.DLL | Library used by NADAPI16.DLL for access to classes that work with file enumeration, file information, and directory monitoring on clients running Windows NT.
 | DEINSDLL.DLL | Library used by SMS Client Setup.
 | IMP.INI | Initialization file that contains settings for IMP16.DLL.
 | INV32CLI.EXE | Program for inventorying clients running the Windows NT platform.
 | ISMIF16.DLL/ ISMIF32.DLL | Library used for status MIF files.
 | MULTPROT.DLL | Library with multi-protocol abstraction layer, used by Remote Control for clients running Windows NT 3.51 and later.
 | NADAPI16.DLL/ NADAPI32.DLL/ NADAPI95.DLL | Library used by the Applications Control program (APPCTLx.EXE) and APPSTART.EXE to manage SMS network applications.
 | QUEUEBUF.DLL | Library used to manage "send buffer" for Remote Control of clients running Windows NT.
 | PROXYDLL.DLL | Library used by the Applications Control program (APPCTLx.EXE).
 | SMS16NET.DLL | Library used by clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | SMS16THK.DLL | Library used by clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | SMS32SHL.DLL/ SMS95SHL.DLL | Library used by clients running Windows NT/Windows 95.
 | SMS95LAN.DLL | Library used by Windows 95 clients for networking.
 | SMS95NET.DLL | Library used by Windows 95 clients for networking.
 | SMS95NW.DLL | Library used by Windows 95 clients for networking with NetWare.
 | SMSCFG.DLL | Library used by the Applications Control program when running the SMS shared application configuration scripts.
 | SMSMS32.DLL | Library used by SMSNET32.DLL for making network calls that are specific to LAN Manager.
 | SMSNET.DLL/ SMSNETS32.DLL | Library used by NADAPI16.DLL/ NADAPI32.DLL to make connections and get information such as user group and server names.
 | SMSNETMS.DLL (SMSNETNW.DLL) | Library used by SMSNET.DLL for making network calls that are specific to LAN Manager (or NetWare). If NetWare is detected, SMSNET.DLL loads SMSNETNW.DLL. If not, it loads SMSNETMS.DLL.
 | SMSNWRES.DLL | Library of resources for SMSNETNW.DLL.
 | SMSRUN32.EXE | Program that reads SMSRUN32.INI on clients running Windows NT to create program groups on the client and then launch SMS client programs.
 | SMSSETU_.DLL | Library used by SMS Client Setup.
 | SMSSU16.DLL/ SMSSU32.DLL | Library used by SMS Client Setup.
 | SNMPELEA.DLL | Library that provides an extension to the SNMP Service, for the SNMP trap sender on clients running Windows NT.
 | SNMPELMG.DLL | Library that contains the locale and language-specific strings used by the SNMPELEA.DLL on clients running Windows NT.
 | VUSER.386 | Device driver used to view command windows on clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | WCHAT32.EXE | Program used for Remote Chat on clients running Windows NT.
 | WSLAVE32.EXE | Program used for specific network operations on clients running Windows NT.
 | WUSER32.EXE | Remote Control agent for clients running Windows NT.
 | WUSERMSG.DLL | Library used by WUSER32.EXE for error messages.
 | _WUSER32.DLL | Library used by WUSER32.EXE.
Windows/SYSTEM | IDIS_NT.DLL | Display driver that works with WUSER32.EXE on clients running Windows NT version 3.51.
 | SMSROUTR.VXD | Windows 95 device driver for SMS network applications.
 | SNMPAPI.DLL | Library that contains the SNMP management API for Windows NT 3.51.
 | VSMSNET.VXD | Device driver for SMS network applications
Windows/SYSTEM/DRIVERS | KBSTUFF.SYS | Driver used to send keystrokes to a client running Windows NT when it is being remotely controlled and no user is logged on.
MS\SMS\BIN | _CLILANG.DLL | Library that contains locale and language-specific strings used by SMSRUN16.EXE.
 | _CLMON32.DLL | Library that contains locale and language-specific strings used by the SMS client monitor for Windows NT (CLIMONNT.EXE).
 | _EDITINI.DLL/ _EDTINNT.DLL | Libraries used for EDITINI.EXE/ EDTININT.EXE, for configuring remote control options from the client.
 | _IDISP16.DLL | Library used by IDISP16.DLL for internationalization resources.
 | _MIF.DLL/ _MIFDOS.DLL | Library used by the MIF Entry program.
 | _WCHAT16.DLL | Library used by WCHAT16.EXE for internationalization resources.
 | _WSLAV16.DLL | Library used by WSLAVE16.EXE for internationalization resources.
 | _WUSER.DLL | Library used by the Remote Control agent (WUSER.EXE).
 | APPCTL16.EXE/ APPCTL32.EXE/ APPCTL95.EXE | Configures SMS shared applications.
 | APPRES16.DLL/ APPRES32.DLL/ APPRES95.DLL | Library that contains locale/language specific-strings used by the Applications Control program.
 | CLIMONNT.EXE | Program for monitoring and inventory on clients running Windows NT.
 | COEXIST.DLL | Library used by IDISP16.DLL to perform function-hooking tasks.
 | EDITINI.EXE/ EDITININT.EXE | Program for configuring remote control options from the client.
 | HELP.HLP | Help file for clients running MS-DOS.
 | IDISP16.DLL | Library used by Remote Control as a display driver to capture screens on clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | IDIS_LM.DLL (IDIS_IPX.DLL) | Library used by WUSER.EXE for network-specific calls.
 | IMP16.DLL | Library that provides a multi-protocol abstraction layer for Remote Control of clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | IPCONFIG.EXE/ WINIP95.EXE | Program used by clients running Windows for Workgroups/Windows 95 to manipulate and display basic network configuration information, used by the Inventory Agent.
 | INV32CLI.EXE | Program for inventorying clients running the Windows NT platform.
 | MIFDOS.EXE/ MIFWIN.EXE | MIF Entry program for completing forms that are reported as MIF files.
 | NNP.EXE | Program Group Control program for Windows 95.
 | PCM16R.DLL/ PCM32R.DLL | Library that contains locale/language-specific strings used by Package Command Manager.
 | PCMDOS.EXE | Package Command Manager program for MS-DOS. PCMDOS.EXE calls a series of related programs named PCMDOS_2.EXE, PCMDOS_3.EXE, and PCMDOS_3.EXE.
 | PCMDOS_2.EXE | Program that provides network connection code for PCMDOS.EXE.
 | PCMDOS_3.EXE | Program that provides status reporting for PCMDOS.EXE.
 | PCMDOS_4.EXE | Program that provides the text-based user interface for PCMDOS.EXE.
 | PCMWIN16.EXE/ PCMWIN32.EXE | Package Command Manager program for Windows version 3.1, Windows for Workgroups, Windows 95, and Windows NT.
 | QBASIC.EXE | Program that interprets BASIC programming, used on MS-DOS clients to display help files.
 | SIGHT.OVL | Overlay used by USERTSR.EXE and USERIPX.EXE to access data.
 | SM16.CNT/ SM32.CNT | Help contents file for SMS clients running Windows 95 or Windows NT.
 | SM16.HLP/ SM32.HLP | Help file for SMS clients running Windows.
 | SMSOS2AG.EXE | Program that enables Package Command Manager to gain access to SMS logon servers on the network.
 | SMSRUN16.EXE | Program that reads SMSRUN16.INI on clients running Windows version 3.1, Windows for Workgroups, Windows 95, or OS/2 to create program groups on the client and then launch SMS client programs.
 | SMSWORK.EXE | Program that queues work to be done after a system restart.
 | START.EXE | Program required by clients running Windows 95 as part of the operating system.
 | UINFO.XNF | Default MIF form for clients.
 | USERTSR.EXE (USERIPX.EXE) | As a terminate-and-stay-resident (TSR) program on clients running MS-DOS and Windows version 3.1, this program displays a computer's configuration and provides Help Desk features for the SMS Administrator.
 | WCHAT16.EXE | Program used for Remote Chat on clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | WOUDAT16.EXE | Program used for diagnostics on clients running Windows 3.1, Windows for Workgroups, and Windows 95.
 | WSLAVE16.EXE | Program used for File Transfer on clients running Windows 3.1, Windows for Workgroups, or Windows 95.
 | WUSER.EXE | Remote Control agent for clients running Windows 3.1, Windows for Workgroups, and Windows 95.
MS\SMS\DATA | CL_DOS.MOD/ CL_WIN.MOD/ CL_NT.MOD/ CL_OS2.MOD/ CL_W95.MOD | File that lists changes made to the client (not including copying files). Note that this file is not an exact copy of the CL_X.MOD file on the SMS logon server.
 | CL_DOS.TXT/ CL_WIN.TXT/ CL_NT.TXT/ CL_OS2.TXT/ CL_W95.TXT | File that lists changes made to the client (not including copying files). Note that this file is not an exact copy of the CL_X.TXT file on the SMS logon server.
 | CLIENT.BAT | Batch file created by SMS Client Setup and used by clients running MS-DOS, Windows version 3.1, Windows for Workgroups, and Windows 95 to run SMS components at startup.
 | CMNDHIS.DOS/ CMNDHIS.WIN/ CMNDHIS.NT | Created on clients when the Inventory Agent is run with a resync command. The Inventory Agent reads this file to find out if it has already run a resync.
 | DOMAIN.INI | Initialization file used by SMS client programs.
 | PCMHIST.REG | Registry containing Package Command Manager status information. This file is created on each client that runs the Package Command Manager to store package information. If PCMDOS.EXE and PCMWIN16.EXE both run on the same client, they share access to a single PCMHIST.REG.
 | SMSRUN16.INI/ SMSRUN32.INI | Initialization files used by SMSRUN16 and SMSRUN32. This ASCII file tells SMSRUN which program group icons to set up.
MS\SMS\LOGS | AUDIT16.LOG/ AUDIT32.LOG | Log file for software auditing on the client. This file exists only after an audit job has run.
 | CLI_X.LOG | Log file for SMS Client Setup.
 | CLIMON.LOG | Log file for the Windows NT Client Monitor (CLIMONNT.EXE).
 | INV32CLI.LOG | Log file for the Windows NT Inventory Agent.
 | NNP.LOG | Log file for Program Group Control for Windows 95 and Windows NT.
 | PCMDEBUG.LOG | Log file containing detailed trace information, created when the /DEBUG command-line switch is used with PCMDOS.EXE, PCMWIN16.EXE, or PCMWIN32.EXE.
 | PCMDOS.LOG | Log file that provides troubleshooting information for Package Command Manager on clients running MS-DOS.
 | PCMWIN.LOG | Log file that provides troubleshooting information for Package Command Manager on clients running Windows.
 | PGC.LOG | Log file for Program Group Control.
 | SMSRUN.LOG | Log file for the SMSRUN program.


Macintosh Components

To start inventory collection for the first time, a user on a Macintosh client must manually connect to the Windows NT Services for Macintosh logon server to run the Installer program. After that, inventory collection is automatic at system startup.

To run Installer, the user selects the Chooser to connect to the SMS_SHR volume on the SMS logon server, to locate the MAC.BIN folder. When Installer is run from the MAC.BIN folder, the SMS files and INVMac program are copied to the client. Restarting the Macintosh then runs INVMac that generates client files, including SMS.INI and all local history files. INVMac also starts the Package Command Manager program (PCMMac) on the Macintosh. When a package is first run from the Package Command Manager, PCMMac generates the PCMHIST.REG file, which contains package status information.

The following table lists SMS components on the Macintosh.

Component | Description
SMS.INI | Initialization file that contains configuration information for inventory and Package Command Manager on the client. This file is located in System Folder:Preferences: Microsoft SMS and contains a unique ID used by SMS to identify the client.
Help on Help | Help file located in System Folder:Extensions: Microsoft:Help.
Microsoft Help | Help file located in System Folder:Extensions: Microsoft:Help that runs the help files.
Foxpro Help | Help file located in System Folder:Extensions:Microsoft: Help that runs Microsoft Help as a standalone application.
DOMAIN.INI | When INVMac runs, it creates a local SMS.INI file as well as two files that store the hardware and software inventory history: InvHWScanResult and InvSWScanResult.
INVMac | Program located in System Folder:Startup Items that generates the SMS.INI file, updates SMS logon server files, performs hardware and software inventory, and starts PCMMac.
InvHWScanResult | Local history file located in System Folder:Preferences: Microsoft SMS for hardware inventory.
InvSWScanResult | Local history file located in System Folder:Preferences: Microsoft SMS for software inventory (not present if no inventory is requested).
PCMHIST.REG | File that contains Package Command Manager package status information. This file is created on each client when the Package Command Manager stores package information (when it is required to run or hide a package).
PCMMac | Package Command Manager program for Macintosh that is launched by INVMac and located in System Folder:Preferences:Microsoft SMS.
Microsoft SMS Client Help | Help file for PCMMac. Located in System Folder:Extensions:Microsoft:Help.
MIFMAC | MIF Entry program for completing forms that are reported as MIFs. Located in System Folder:Preferences: Microsoft SMS:BIN.


SMS Client Setup

There are three versions of the SMS Client Setup program, which support the client operating systems, as shown in the following table.

Client operating system | Client setup file
Windows NT (version 3.1 or later) | LOGON.SRV\platform.BIN\CLI_NT.EXE
MS-DOS (version 5.0 or later), Windows version 3.1, Windows for Workgroups, and Windows 95 | LOGON.SRV\X86.BIN\CLI_DOS.EXE
OS/2 version 2.11 and OS/2 Warp | LOGON.SRV\X86.BIN\CLI_OS2.EXE

Macintosh computers use the Installer program to set up and configure the client.

Caution

SMS Client Setup can fail on computers running the MS-DOS VSAFE utility. VSAFE, which is loaded into memory, is an MS-DOS utility that monitors a computer for viruses.

The SMS Client Setup program performs the following operations on clients running MS-DOS, Windows version 3.1, Windows for Workgroups, OS/2, Windows 95, and Windows NT:

  • Analyzes the client to determine whether setup, upgrade, or remove actions are necessary.
  • Sets up new clients, copies SMS files, modifies system files, and configures SMS applications to start automatically, if appropriate.
  • Updates SMS client files.
  • Removes specific SMS programs after an administrator deletes a client program.
  • Removes all SMS files, applications, and program groups.

Note

The client DOMAIN.INI file will normally reflect changes faster than the client SMS.INI file, which is only updated when logon scripts are run or the user runs the RUNSMS batch file.

SMS Client Setup uses the [SMS] section of DOMAIN.INI (located in the LOGON.SRV directory on all SMS logon servers) to determine what changes are required on the client. Client configuration changes are made in the Site Properties dialog box. By default, SMS installs and automatically starts all SMS client applications (Package Command Manager, Program Group Control, the remote troubleshooting utilities, and MIF Entry).

SMS Client Setup is called by the SMSLS or RUNSMS batch file (or the system logon script on NetWare clients). The SMSLS batch file runs SMS Client Setup using the /p: option, where /p: specifies a path to the SMS logon server directory (LOGON.SRV). It contains the copy-list file (CL_x.TXT, where x represents the client platform).

Note

The SMSLS.BAT file has been split into two files. Rather than running as a logon script or running it from SMS_SHR, there are now two batch files that start SMS inventory and SMS Client Setup. Also, two new command (.CMD) files have been added to support OS/2 clients.

SMSLS.BAT is used to generate logon scripts and is located in the NETLOGON share. If you upgraded from SMS version 1.0, the old version of SMSLS.BAT is located in SMS_SHR so you can copy custom changes from an existing SMSLS.BAT file to the new SMSLS.BAT file in the NETLOGON share. Delete the old SMSLS.BAT file after the changes are copied. A new file, RUNSMS.BAT, runs manually from SMS_SHR.

To complete its actions on computers running Windows 3.1, Windows 95, Windows for Workgroups, Windows NT, and OS/2, the SMS Client Setup program uses the SMSRUN (SMSRUN16.EXE and SMSRUN32.EXE) and SMSSVR (SMSSVR16.EXE and SMSSVR32.EXE) programs.

The SMSRUN program reads SMSRUN16.INI/SMSRUN32.INI on computers running Windows version 3.1, Windows for Workgroups, Windows NT, or OS/2 to get the full path for SMS client files, and then it creates program groups on the client. SMSRUN also starts SMS components if the Automatically Start This Component options for the components are set in the Site Properties dialog box.

The SMSSVR program upgrades or removes SMS components from the client. SMSSVR then starts the SMS Client Setup program and upgrades or removes files as selected.


Client Setup Command Line Options

You can run SMS Client Setup manually from the appropriate *.BIN subdirectory of the LOGON.SRV directory (SMS_SHR share) on an SMS logon server. You can run SMS Client Setup with one or more command line options. For example, you can initiate the removal of clients by modifying the SMSLS batch file to run SMS Client Setup with the /r option. Users can initiate removal of their client by connecting to the SMS_SHR on their SMS logon server and running SMS Client Setup manually with the /r option, or they can run DEINSTAL.BAT. The syntax for SMS Client Setup is as follows:

{cli_dos | cli_nt | cli_os2} [/r | /u | /f | /p:path | /d:drive | /v | /k]

/r

Removes the SMS client components. With this option, SMS Client Setup must run twice because SMS applications must be stopped before files are removed. This overrides Client settings in the Site Properties dialog box.

/u

Upgrades SMS client components. With this option, SMS Client Setup must run twice because SMS applications must be stopped before files are updated.

/f

Verifies that each SMS client component file is correctly installed and that the client's system files are correctly configured for SMS. With this option, SMS Client Setup must run twice.

/p:path

Specifies the path for the SMS\LOGON.SRV directory. For example, at a client running MS-DOS, from the command prompt, type:

cli_dos /p:R:

Where R: is the connection to the SMS_SHR on the SMS logon server.

You can also use a UNC path. For example:

cli_dos /p:\\SMS_server\SMS_SHR

/d:drive

Specifies the installation drive on the client. By default, SMS is installed on the drive with the largest amount of free space.

/v

Sets verbose mode. SMS Client Setup displays status messages on the client desktop as it completes its tasks.

/k

Specifies that SMS components are not running, and they can be overwritten if necessary.

If conflicting options are used (for example, /r and /u), SMS Client Setup selects the first option.

For information about how SMS Client Setup installs and upgrades SMS components on and removes SMS components from a client, see Chapter 3, "System Flow."


Client Programs

You can use the following programs to configure SMS clients:

  • SETLS
  • Windows NT Client Monitor
  • Inventory Agent
  • SMSRUN
  • Package Command Manager
  • Program Group Control

Each of these programs is described in the following sections.


SETLS Program

The SMS logon script calls the SETLS program to connect to an SMS logon server. SETLS uses information in the SMSLS.INI file to select an SMS logon server from which to run the SMS Client Setup and Inventory Agent programs for a client. SETLS builds a UNC name corresponding to the platform.BIN directory on the SMS logon server (\\servername\SMS_SHR\platform.BIN) and makes the connection. (SETLS will, when necessary, use a path.) Then the client is added to the computer inventory for the SMS logon server's domain. If no SMSLS.INI file is present, SETLS runs SMS programs from the SMS logon server where the SMSLS batch file was run.

SMS uses the Windows NT Directory Replicator service to place SMSLS.BAT, SMSLS.INI, and SETLS on the NETLOGON share of all SMS logon servers running Windows NT and LAN Manager.

Versions of SETLS

To support computers running Windows NT, Windows version 3.1, Windows for Workgroups, Windows 95, MS-DOS, and OS/2, there are three versions of SETLS.

Client operating system | SETLS program | Directory
Windows NT | SETLS32.EXE | LOGON.SRV\platform.BIN
MS-DOS, Windows version 3.1, Windows for Workgroups, and Windows 95 | SETLS16.EXE | LOGON.SRV\X86.BIN
OS/2 | SETLSOS2.EXE | LOGON.SRV\X86.BIN

When you select the Automatically Configure Workstation Logon Scripts option in the Clients dialog box in Site Properties, the Site Configuration Manager copies the SETLS programs (and other SMS components) to the SCRIPTS directory in the REPL$ share on the primary domain controllers in LAN Manager and Windows NT domains. Depending on the microprocessor types supported in the site, the SETLS programs for the specific microprocessor types are copied to the corresponding directory: X86.BIN (x86 microprocessors), ALPHA.BIN (Alpha microprocessors), and MIPS.BIN (MIPS microprocessors).

SETLS includes command line options for connecting a logical drive to a network server, deleting an SMS logon server connection, and running a program file located on a network server.

Command Line Options

The SETLS command line options are:

{setls16 | setls32 | setlsos2} [/m:C] [/d:drive] [/dr:driverange] [/sh:sharename] [/i[:inifile]] [/v[:on]]

{setls16 | setls32 | setlsos2} [/m:D] [/d:drive] [/v[:on]]

{setls16 | setls32 | setlsos2} [/m:E] [/sh:sharename] [/p:programfile] [/pa:argument [...]] [/sn] [/v[:on]] [/i[:inifile]]

/m:C

Makes a network connection using a logical drive letter.

/m:D

Deletes a network connection that uses a logical drive letter.

/m:E

Runs a program file located on a remote server without making a logical drive network connection (the default is to connect).

/d:drive

Specifies a particular drive letter (the default is the next available drive letter).

/dr:driverange

Limits the search for the next available drive.

/sh:sharename

Specifies the share to connect to. The default is SMS_SHR.

/i:[:inifile]

Names the initialization file to use. The default is SMSLS.INI.

/v[:on]

Specifies verbose mode for output messages. The default is off.

/p:programfile

Is a file name or relative path to an .EXE or a .COM file.

/pa:argument

Passes an argument to the program when it runs. If you want to pass the UNC path of the SMS logon server, specify %%SMS_unc%% as the value for this argument. The SETLS program replaces this with the UNC path to the SMS_SHR share of the SMS logon server.

/sn

Indicates that the specified program should not be run on a slow network.


Windows NT Client Monitor

The Windows NT Client Monitor is made up of the CLI_NT.EXE and CLIMONNT.EXE programs. The Windows NT Client Monitor:

  • Copies RAW files from the client running Windows NT to the SMS logon server. Whenever CLI_NT.EXE runs, it copies the files that need to be copied, otherwise CLIMONNT.EXE copies the files.
  • Monitors changes to clients running Windows NT that require the client to be restarted. (This task is performed only by the CLIMONNT.EXE program.)

CLIMONNT.EXE is started by SMSRUN32.EXE when Windows NT is started and runs in the background as long as the user is logged on. When a directory change notification is received, CLIMONNT.EXE picks up RAW files as soon as they appear and copies them to the SMS logon server. CLIMONNT.EXE uses a polling interval to check whether the files on the SMS logon server (DOMAIN.INI, PKG_16.CFG, RESYNC.CFG) have changed and need to be copied.

CLI_NT.EXE

This program runs from the SMSLS.BAT or RUNSMS.BAT batch file when the user logs on. The CLI_NT.EXE program:

  • Copies DOMAIN.INI, PKG_16.CFG, and smsid.CFG from the SMS logon server to the client if the versions on the client are not current.
  • Checks to see whether a RAW file is present on the client; if so, it copies the file to the SMS logon server and deletes the copy on the client.

CLIMONNT.EXE

This program is started by SMSRUN32.EXE when a user logs on and runs the client continuously. The CLIMONNT.EXE program:

  • On a polling interval, copies DOMAIN.INI, PKG_16.CFG, and smsid.CFG from the SMS logon server to the client if the versions on the client are not current.
  • Checks to see whether a RAW file is present on the client; if so, it copies the file to the SMS logon server and deletes the copy on the client.
  • Monitors the registry for configuration changes that require the client to be restarted.


Inventory Agent

Every SMS client has a version of the Inventory Agent program as described in the following table.

Client operating system | Inventory Agent file name
Windows NT | INVWIN32.EXE, INV32CLI.EXE
Windows 95 | INVDOS.EXE
Windows for Workgroups | INVDOS.EXE
Windows version 3.1 | INVDOS.EXE
MS-DOS (version 5.0 or later) | INVDOS.EXE
Macintosh (version 7.0.0 or later) | INVMac
OS/2 version 2.11 and OS/2 Warp | INVOS2.EXE

Except for Macintosh clients, the Inventory Agent runs when the SMSLS or RUNSMS batch file is called. For clients running NetBIOS protocols, such as NetBEUI and TCP/IP, the Inventory Agent program runs from the SMSLS.BAT logon script. For NetWare IPX-based clients, Inventory Agent runs as part of a NetWare system logon script.

Inventory Agent for Windows version 3.1, Windows for Workgroups, MS-DOS, Windows 95, and Windows NT generates *.RAW files. The Inventory Agent programs for Macintosh and OS/2 clients create ASCII MIF files. Both *.MIF and *.RAW files become binary MIF files after being processed by the Inventory Processor.

On all clients, the Inventory Agent:

  • Scans the client for inventory (hardware, software, and ISV MIF files).
  • Collects files to include in the inventory.

Inventory on Clients Running Windows NT

The SMS Client Inventory service (INV32CLI.EXE) is installed on Windows NT-based clients by the Client Configuration Manager, if the SMS Inventory Agent (INVWIN32.EXE) is not running. SMS Client Inventory runs under the LocalSystem security context and thus provides a more complete inventory. The SMS Client Inventory:

  • Reads DOMAIN.INI, PKG_16.CFG and smsid.CFG from MS\SMS\DATA on the client.
  • Takes inventory based on the inventory frequency specified by the administrator in the SMS Administrator.
  • Places its inventory RAW files locally on the client in the MS\SMS\INVDATA directory.

The inventory RAW file on the client is copied to the SMS logon server by Client Monitor. If no user is logged on to the client when inventory is collected, Client Monitor will not start until the next time a user logs on.

As in previous releases of SMS, INVWIN32.EXE is also an Inventory Agent for Windows NT-based clients. INVWIN32.EXE is launched from SMSLS.BAT or RUNSMS.BAT when the user logs on. The INVWIN32.EXE program:

  • Reads input files DOMAIN.INI, PKG_16.CFG, and RESYNC.CFG directly from the SMS logon server.
  • Checks whether this is a different site/domain from the site/domain previously established. If the site/domain is different, it checks to see if inventory was collected against this same new site/domain for a specified number of consecutive times (defaults to 3). If not, it prints a message and exits. If so, it changes the site/domain information in SMS.INI and continues.
  • Builds (or rebuilds) the list of SMS logon servers in SMS.INI from data in the DOMAIN.INI file.
  • Takes inventory based on the inventory frequency specified by the administrator in the SMS Administrator and only if it determines that inventory has not been taken within a reasonable time by the SMS Client Inventory service (INV32CLI.EXE).
  • Places its inventory RAW file on an appropriate SMS logon server.

Inventory on Clients Running MS-DOS, Windows 3.1, Windows for Workgroups, and Windows 95

On clients running MS-DOS, Windows version 3.1, Windows for Workgroups, and Windows 95, the Inventory Agent always reports the protocol used while connecting to the SMS logon server. If information about other protocols is available to the Inventory Agent, it will report this also.

On clients running Windows for Workgroups or LAN Manager, you must run the SMSLS.BAT or RUNSMS.BAT file or Inventory Agent using the Full (or Enhanced) Redirector. If you use the Basic Redirector, the Inventory Agent will either not report the inventory or prompt you for an SMS ID. It can also quit the process and display an error. To correct this, start the network software using the Full or Enhanced Redirector.

Inventory Agent Command Line Options

There are four Inventory Agents, each supporting different command line options:

Inventory agent | Client operating system
INV32CLI | Windows NT
INVWIN32 | Windows NT
INVDOS | MS-DOS, Windows 3.1, Windows for Workgroups, Windows 95
INVOS2 | OS/2

These commands are described in the following sections.

INV32CLI

The syntax for INV32CLI is:

inv32cli /T minutes

Where minutes sets the sleep interval. Using this option temporarily overwrites the initial 24-hour default value. This setting will last until the service is stopped and restarted.

INVWIN32

To run INVWIN32 as an executable file, the syntax is:

invwin32 /E [/F] [/I] [/V] [/L:\\SMS server\SMS_SHR]

To run INVWIN32 as a service, the syntax is:

invwin32 [/F] [/I] [/T minutes]

/E

Causes INVWIN32 to be called as an executable file, rather than a service.

/F

Forces an immediate hardware and software inventory.

/I

Performs software and hardware inventory only (does not perform any other task such as downloading or collecting files).

/V

Specifies verbose mode. Displays status messages during execution.

/L:\\SMS server\SMS_SHR

Specifies an SMS server to use for inventory input and output files. Overwrites the specified server in SMS.INI.

/T minutes

Sets the service sleep interval to minutes, temporarily overwriting the default value of 24 hours. This setting will last until the service is stopped, and then restarted.

When running INVWIN32 as a service, specify its switches in the Startup Parameters box in the SMS Service Manager.

INVDOS

The syntax for INVDOS.EXE is:

invdos [/F] [/M] [/I] [/V] [/L:\\SMS server\SMS_SHR | /N\\server /P share]

/F

Forces an immediate hardware and software inventory.

/M

Forces INVDOS to request a unique computer name.

/I

Performs software and hardware inventory only (does not do any other task such as downloading or collecting files).

/V

Specifies verbose mode.

/L:\\SMS server\SMS_SHR

Specifies an SMS server to use for the inventory input and output files. Overwrites the specified server in SMS.INI.

/N\\server /P share

Specifies the location for inventory output files. Overwrites the InventoryCollectionPoint entry in SMS.INI. These switches will also overwrite the /L option.

INVOS2

The syntax for INVOS2.EXE is:

invos2 [/V] [/L:\\SMS server\SMS_SHR]

/V

Specifies verbose mode.

/L:\\SMS server\SMS_SHR

Specifies an SMS server to use for the inventory input and output files. Overwrites the specified server in SMS.INI.

Temporary Files

The SMSSAFE.TMP file is created by the Inventory Agent to record the status of hardware inventory. Every time the Inventory Agent runs, it creates drive:\SMSSAFE.TMP. When it successfully finishes, it deletes this file. If the Inventory Agent doesn't complete inventory successfully, the file remains as a signal that something went wrong during the previous inventory collection. When it runs again, the Inventory Agent writes entries to the empty SMSSAFE.TMP for each test it runs. The results are marked COMPLETED after successfully doing each test or CRASHED, if a hardware test fails. The next time the Inventory Agent runs, it reads the file again; all tests marked CRASHED are skipped and their failure is recorded and written to the [WorkstationStatus] section of the SMS.INI file. After moving the failed tests to the SMS.INI file, the SMSSAFE.TMP file is deleted. The next time the Inventory Agent runs, it will detect the failed tests in the SMS.INI file and skip failed hardware tests.

When you troubleshoot a hardware inventory problem, you may need to disable portions of the hardware detection during the SMS inventory on the client. This can be accomplished by creating your own SMSSAFE.TMP file.

To create a SMSSAFE.TMP file, use a text editor to add valid entries of hardware devices or parameters you want the hardware detection to bypass (listed below). For example, if you want to bypass the mouse detection, enter the following in the SMSSAFE.TMP file:

MouseInfo=CRASHED

The following are valid entries for SMSSAFE.TMP (FailedHardwareChecks):

BanyanVines
BiosInfo
CMOSMemory
CommPorts
ComputerConfig
ComputerName
ConventionalMemory
DeviceInfo
Disks
Dma
DPMIMemory
Drive<X>
EMMMemory
EMMMemoryInfo
ExtendedMemory
GamePorts
IRQInfo
Keyboard
Lanman
LanmanInfo
LanManNetcardInfo
Lantastic
LantasticInfo
MouseInfo
MSNet
NetBios
Novell
NovellInfo
NovellNetcardInfo
PrinterPorts
TSRInfo
VCPIMemory
Video
WolverineInfo
XMSMemory

When a failed hardware component is fixed or replaced, remove the appropriate FailedHardwareChecks entry from the [WorkstationStatus] section in SMS.INI and remove the SMSSAFE.TMP file (if it only referenced one component). Start the client again and run the Inventory Agent to include the component.


SMSRUN Program

The SMSRUN program (SMSRUN16.EXE and SMSRUN32.EXE) configures SMS program groups and starts SMS applications on clients running OS/2, Windows NT, Windows 95, Windows version 3.1, or Windows for Workgroups.

For clients running OS/2, Windows 95, Windows version 3.1, or Windows for Workgroups, SMS Client Setup modifies the WIN.INI file to load SMSRUN16.EXE each time Windows starts. SMSRUN16 reads SMSRUN16.INI to see which program groups to create and which applications to start.

On clients running Windows NT, SMSRUN32.EXE runs from the Load value in the HKEY_CURRENT_USER\SOFTWARE\Microsoft\Windows NT \CurrentVersion\Windows key in the Windows NT registry, so it runs at startup. SMSRUN32 uses SMSRUN32.INI to create program groups on the desktop and start applications as specified in the [Startup] section.


Package Command Manager

The Package Command Manager program runs on every client and supports the following operating systems.

Client operating system | Package Command Manager file
Windows NT (version 3.1 or later) | PCMWIN32.EXE
Windows version 3.1, Windows for Workgroups, OS/2 version 2.11, OS/2 Warp, and Windows 95 | PCMWIN16.EXE
MS-DOS (version 5.0 or later) | PCMDOS.EXE
Macintosh (version 7.0.0 or later) | PCMMac

The Package Command Manager:

  • Checks SMS.INI for the location of the PCMHIST.REG registry, specified polling intervals, and other Package Command Manager options.
  • Checks the SMS logon server at startup for new or pending packages that have not been run or archived. The service allows automated installation to occur based on the polling interval, unless the user chooses the Package Command Manager icon, which causes an immediate check.
  • Displays the Package Command Manager in the foreground whenever a new, visible package is available or whenever the user chooses the Package Command Manager icon.
  • Runs the package commands that install packages on an individual client.
  • Lets users at client destinations specify which packages to install.
  • Stores package information in PCMHIST.REG.
  • Returns job status information to the SMS logon servers.

After running a package, the Package Command Manager modifies PCMHIST.REG indicating that the package was run.

Windows NT-based SMS servers also support the Package Command Manager service (PCMSVC32.EXE). This service allows package installation on unattended computers running Windows NT. If a user is not logged on when a package arrives at a target computer running Windows NT, the Package Command Manager service runs packages in the background (if the package supports it); if a user is logged on, the Package Command Manager program installs the package. By default, the PCMSVC32.EXE file is installed only on computers running Windows NT Server that are SMS site, helper, or logon servers.

When SMS installs client components on an OS/2 2.11 client, it also installs the SMSOS2AG.EXE file. SMSOS2AG.EXE enables Package Command Manager to gain access to SMS logon servers on the network. This file monitors the arrival of new packages and reports the package command status to the SMS system and package distribution servers.


Program Group Control

Program Group Control includes two programs (APPSTART and Applications Control [APPCTL]) that manage the environment for SMS network applications on SMS clients running Windows version 3.1, Windows for Workgroups, Windows 95 or Windows NT.

APPCTL manages connections to the SMS network application server and ensures that the assigned SMS network application program groups are built when Windows is started. The user's environment information is obtained from the Program Group Control database. When a user clicks an icon to start an SMS network application, APPSTART retrieves a list of servers from the Program Group Control database and permits access to an available server. After connecting to that server, APPCTL sets up the Windows environment so the application runs correctly, which allows APPSTART to start the application.

APPCTL Command Line Options

{APPCTL16 | APPCTL32 | APPCTL95} [/stop ] [/hide] [/deinstall] [/disable:yes]

/stop

Stops the current APPCTL session.

/hide

Hides the Program Group Control window. By default, this window appears when APPCTL checks for new applications. Before attempting to hide the window, use the /stop option to stop APPCTL.

To make the Program Group Control window reappear after hiding it, use the /stop option to stop APPCTL, and then choose the Program Group Control icon.

/deinstall

Removes all SMS program groups from the Program Manager and the local registry.

/disable:yes

Disables Program Group Control on the client.

General Guidelines for Program Group Control

Program Group Control can reconfigure an SMS shared application if it determines that its registry entries are corrupted. When the reconfiguration program runs, it selectively removes files from the directory. To prevent deleting user-created files, SMS Setup records the date and time the application was installed and stores this information in the registry. However, if an application is removed, reinstalled, and then removed again, any files modified after the first installation but before the second installation are deleted because its date will not be more recent than the second installation time.

An executable file (DOSETUP.EXE) will run a user-specified installation program under Program Group Control. DOSETUP.EXE allows an arbitrary installation program to be run by Program Group Control. This program would normally be specified as the ConfigurationScript entry in the [Program Item Properties i] section of a PDF file. The command-line syntax is:

dosetup RegName CommandLine

where RegName has the same value as the RegistryName entry in the same section of the PDF, and CommandLine is any valid command line.

For example, the following command runs the installation program for the Microsoft Access 2.0 Service Pack:

dosetup acs2pak setup.exe

DOSETUP provides a mechanism to run an installation program and sets SMS registry status flags required by Program Group Control.

DOSETUP runs the specified command line and manages the status entry under the program item's registry key (HKEY_CLASSES_ROOT\SMS \APPLICATIONS\regName\Configuration\Status). The status entry must be set to UNFINISHED, FAIL, or SUCCESS. DOSETUP operates like SMSSETUP in most respects; it displays the SMS Setup screen, reports errors, and does post-processing following a system restart.

Post-processing sets an application's status flag to SUCCESS. DOSETUP initially sets an application's status to FAIL in case anything goes wrong during processing. To handle a possible system restart by an installation program, DOSETUP sets the status to UNFINISHED immediately before running the user's command line. When the installation program ends, or when Program Group Control Start reruns DOSETUP following a system restart, the status is reset to SUCCESS. An installation program cannot pass an error message to DOSETUP.

DOSETUP is installed in the MSTEST directory on the SMS logon server.

Disabling Program Group Control on Clients

When Program Group Control runs on the client, it can take a few minutes to count user groups and set up the Program Group Control environment. This can happen even when Program Group Control has not been set up for that user. If you are using Program Group Control in your site, and users want to disable it, you can use the Registry Editor or a Program Group Control command-line switch.

To disable Program Group Control using the Registry Editor, add the registry key HKEY_CLASSES_ROOT\SMS\DISABLE_PGC. To enable Program Group Control on the computer, remove this key.

To disable Program Group Control from the command line, add the /DISABLE:YES switch to the APPCTLxx command. For instance, appctl16 /disable:yes disables Program Group Control on a client running 16-bit Windows. If an instance of Program Group Control is already running when it is disabled on the computer, Program Group Control will be disabled the next time the user logs on.

Program Group Control Error Messages

After SMS is installed in a site server domain and a client is added, you may see the following message when running Program Group Control:

Program Group Control: Could not open the application

database because servers are missing from the SMS.INI. Resolve

this problem by rerunning Client Setup.

If you add a client to the site using the SMSLS or RUNSMS batch file (or SMS Client Setup) from an SMS logon server with no servers in the [Servers] section of the DOMAIN.INI file, Program Group Control displays the preceding message.

After SMS is installed in the site server domain, make sure that all SMS logon servers are listed in the [Servers] section of the DOMAIN.INI file on the SMS_SHR share of each SMS logon server in the site server domain. Correct this error by rerunning the SMSLS or RUNSMS batch file or SMS Client Setup when there are one or more servers listed in the [Servers] section of DOMAIN.INI.

A user may see the following message after trying to use an SMS network application:

Failed to connect to SMS network server. Cannot

determine which groups the user belongs to. Please

contact your administrator.

This means the client cannot locate any of the package servers.

To correct this:

1. Examine the PGC.LOG file in the MS\SMS\LOGS directory on the client. This file may contain specific information regarding the failure.

2. Examine the [servers] section of the SMS.INI file on the client.

3. Set up a network connection to the SMS_SHR share for one of the servers listed in this section.

4. Within the SMS_SHR share, connect to the APPCTL.BOX\ DATABASE directory and look for files with .HAF and .HGF extensions. There should be one .HGF file for each program group available to the user, and there should be one .HAF file for each program item in the assigned program groups. If there are no files with these extensions, it can indicate that the program groups for have not been distributed to this site, or that the user at the client does not have permission to view the files in the share.


Client Files Modified by SMS

The following table lists client files that are modified during SMS operations.

File

Modifications

SMS.INI

The first time SMS Client Setup is run, it writes the SMS ID to this file. If SMS.INI is deleted, a new ID is assigned and SMS assumes this is a new computer. Then the SMS.INI file is updated with new information from DOMAIN.INI on the SMS logon server every time the user runs SMS Client Setup.

When a user chooses the Help Desk Options icon in the SMS Client program group and makes changes to the default remote control settings, the EDITINI.EXE file writes these changes to the [SIGHT] section of SMS.INI. This occurs only on Windows-based clients that support remote control.

When a user changes settings in the Package Command Manager Options dialog box, the Package Command Manager program writes these changes to the [Package Command Manager] section of SMS.INI.

The Inventory Agent logs any hardware failures encountered during inventory, and it writes the date and time of the last hardware and software inventories.

SYSTEM.INI

For clients running Windows 95, SMS Client Setup modifies lines in the [386ENH] section as follows:

Device=\Windows\vuser.386
NetHeapSize=48

For clients running Windows version 3.1 or Windows for Workgroups, SMS Client Setup modifies lines in the [386ENH] section as follows:

Device=\Windows\vuser.386
NetHeapSize=56

VUSER.386 enables the remote troubleshooting utilities to run. Increasing NetHeapSize provides more memory for SMS remote troubleshooting utilities. It also adds device drivers (SMSROUTR.VXD and VSMSNET.VXD) for clients running Windows 95.

WIN.INI

For clients running Windows version 3.1, Windows for Workgroups, or Windows 95, SMS Client Setup for Windows modifies the LOAD= parameter in the [Windows] section to call SMSRUN16.EXE (LOAD=C:\MS\SMS\BIN \SMSRUN16.EXE).

AUTOEXEC.BAT

On clients running MS-DOS, Windows version 3.1, Windows 95, and Windows for Workgroups, SMS Client Setup modifies AUTOEXEC.BAT to call CLIENT.BAT if the remote troubleshooting utilities are installed or if Package Command Manager for MS-DOS is enabled. This modification is inserted before instructions to run Windows because SMS Client Setup looks for strings containing "Win" to determine where to insert the CLIENT.BAT file.

CLIENT.BAT

SMS Client Setup modifies CLIENT.BAT to run the remote support TSR (usertsr or useripx) on clients running MS-DOS and Windows 3.1, and Package Command Manager for MS-DOS, if appropriate. SMS Client Setup also adds SMSWORK.EXE to all clients except those running Windows NT.

SMSRUNx.INI

For clients running Windows 3.1, Windows 95, and Windows for Workgroups (SMSRUN16.INI), and Windows NT (SMSRUN32.INI), SMS Client Setup modifies this file to define the SMS client program groups and to indicate which SMS applications to load and start automatically.

PCMHIST.REG

This file is generated the first time Package Command Manager runs or archives a package. The file stores information about packages, such as when it was installed or archived.

SMSSAFE.TMP

Inventory Agent creates this file to record hardware inventory status. Every time Inventory Agent runs, it creates drive:\SMSSAFE.TMP. Upon successful completion, it deletes the file. If the Inventory Agent does not complete inventory successfully, the file remains as a signal that something went wrong during the previous inventory collection.

When it runs again, Inventory Agent writes entries to the empty SMSSAFE.TMP file. The status is recorded either as COMPLETED if a test was successful or CRASHED, if a hardware test failed. The next time Inventory Agent runs, it reads the file again. All tests marked CRASHED are skipped and their failed status is written to the [WorkstationStatus] section of SMS.INI.

STARTUP.CMD

Runs the SMSOS2AG.EXE file on OS/2 clients.

Registry database files

On clients running 16-bit Windows, the REG.DAT registry file is modified by SMS Client Setup, SMSRUN16.EXE, and Program Group Control.

On clients running Windows NT, SMS Client Setup, SMSRUN32.EXE, and Program Group Control modify the Windows NT registry.


Troubleshooting

If you are having trouble installing or running the SMS client software, check the following:

1. Make sure the client has access to the network.

Use File Manager or command line options to establish a connection to the SMS logon server. If a connection doesn't occur, it can indicate a network problem or that a common protocol has not been established.

2. Verify that the SMS.INI operating system to the network-type keys match the client's operating system and network type.

If they do not match, rerun RUNSMS.BAT, RUNSMS.CMD, or the logon script.

3. Verify that the appropriate Windows network drivers are installed on clients running Windows 3.1, Windows for Workgroups, or Windows 95.

Examine the network.drv = entry in the Windows SYSTEM.INI file. One of the following entries should be present: LANMAN21.DRV, WFWNET.DRV, MSNET.DRV, or NETWARE.DRV. For Windows 95, this value may be something like "Microsoft Windows Network (version 3.11)." If the appropriate driver is not loaded, Package Command Manager and Program Group Control will not start.

For clients running Windows 95, look at the Network settings in the Control Panel to verify network support.

4. Verify that the client is running the latest patches of all software.

Microsoft Operating System patches are available on the Windows NT Server compact disc or from CompuServe. The Windows NT Server version 3.51 compact disc contains updated modules for the following client network operating systems:

  • Network Client version 3.0 for MS-DOS
  • Windows for Workgroups version 3.11
  • LAN Manager version 2.2c
  • TCP/IP-32 for Windows for Workgroups, version 3.11
  • Remoteboot Service for Windows NT Server version 3.51
  • Additional Network Interface Card (NIC) Drivers from the Windows Driver Library (WDL)

5. On the client, ensure that SMS components have not been moved to the Startup group.

If SMS components are run from the Startup group, SMS upgrades fail. If this happens, you can install or reinstall SMS by removing the SMS component from Startup, restarting Windows, and rerunning SMSLS.BAT or RUNSMS.BAT.

6. Make sure the user logon account for the client has Read permissions for the SMS logon server's SMS_SHR.

7. View the CLI_x.LOG file for reported problems on the client.

8. For Run Command On Workstation packages:

  • Make sure that packages are designated for the appropriate operating systems. For example, if a package is targeted for clients running MS-DOS, it will not appear on clients running Windows version 3.1.
  • The date and time on the client must be consistent with the date and time on the SMS server. If these values are not the same, the package expiration time could possibly occur before the package arrives at the client.
  • Check the event log for failure explanations. Likely problems include insufficient disk space on a client or a network connection failure. In the latter case, try to make the network connection with the net use command.

9. Check the FilesNotDownloaded entry in SMS.INI. Component problems can sometimes be caused by missing files.

10. For problems with SMS Client Setup:

  • Verify that the path is not too long and the Windows directory is at the beginning.
  • Ensure that WINVER.EXE exists in the Windows directory.
  • Temporarily disable virus protection software.

11. For problems with inventory, restart the client and run inventory again. Then check the FailedHardwareChecks entry in SMS.INI.


Chapter 3 - System Flow

This chapter describes the Microsoft Systems Management Server (SMS) process for the following operations:

  • SMS infrastructure management, including how sites, servers, and clients are installed and maintained.
  • Inventory collection and maintenance, including how SMS processes the various types of inventory-related files.
  • Software Distribution, including how SMS processes jobs, sets up SMS network applications, and selects default distribution servers.
  • SMS event collection and reporting.
  • Remote troubleshooting.

You can use this information to track the flow of data and control files within and between sites.


SMS Infrastructure

The following sections describe primary and secondary site installation, SMS logon server component installation, and SMS client installation.


Primary Site

A primary site has its own SQL Server database to store the system, package, inventory, and status information for the primary site and the sites beneath it in the hierarchy. It also has administrative tools to directly manage all sites in the site hierarchy.

A primary site must be installed from the SMS Setup program that is included in the Microsoft Systems Management Server version 1.2 compact disc. When a primary site is installed for the first time, it is a standalone central site. Once a primary site is installed, you can use the SMS Administrator to integrate the new site and any of its subsites in the hierarchy of another SMS system.

Installing a Primary Site

When you run the SMS Setup program to install a primary site, it begins by determining the available language and platform included on the Microsoft Systems Management Server version 1.2 compact disc. It then decompresses files and writes them to disk as specified in the SYSTEM.MAP file. SMS Setup reads SYSTEM.MAP directly from the Microsoft Systems Management Server version 1.2 compact disc, and then copies it to your disk for later use by the SMS Administrator and the Hierarchy Manager and Site Configuration Manager services. In order to interact with logon servers and clients running various CPU platforms and languages, SMS Setup downloads binaries for all supported configurations according to the directory structure mapped out in SYSTEM.MAP. The SYSTEM.MAP file is also used to manage client files.

While copying files to the hard disk and creating the directory tree, SMS Setup initiates SQL Server database operations. Once file installation and database operations are complete, SMS Setup starts the Hierarchy Manager and Site Configuration Manager services and writes information to the Windows NT registry under the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS

The Identification, Setup, and SQL Server keys contain information relevant to the setup process:

  • The Identification key contains the Windows NT domain and server names for the site server and the name of the SMS installation directory.
  • The Setup key records the SMS version and user and organization names.
  • The SQL Server key stores database and device names, as well as the encrypted SQL Server password and account.

During the installation process, the Hierarchy Manager service reads and writes information to and from the SQL Server database. The Site Configuration Manager service sets up services, domain management, shares, and so on. As part of the installation process, the Hierarchy Manager creates a temporary site control file (SMS\SITE.SRV\SITECFG.BOX\_INIT.CT1), which contains all proposed configurations for a site. The Hierarchy Manager passes this file to the Site Configuration Manager, which carries out the proposed configuration.

After the Site Configuration Manager completes the site configuration instructions, it sends a site control file (*.CT2) back to the Hierarchy Manager. The Hierarchy Manager uses this site control file to write configuration data to the site database. The Site Configuration Manager also copies this file to a permanent text file (SITECTRL.CT0) in the SITE.SRV\SITECFG.BOX directory. Note that this process repeats each time there is a proposed change to the site configuration. Each site has its own SITECTRL.CT0 file.

As part of site configuration, the Site Configuration Manager starts the following services: SMS Executive, Client Configuration Manager, Inventory Agent for Windows NT, and the Package Command Manager for Windows NT. The SMS Executive service, in turn, starts additional SMS components such as the Despooler and Scheduler. The SMS Setup program creates the Systems Management Server program group and icons.

Installation on the site server is now complete. Note that if events or errors occur during setup, they are written to the Windows NT event log. You can also view the SMSSETUP.LOG file to trace the actions and errors logged by the SMS Setup program. SMSSETUP.LOG is located at the root of the first hard disk drive on the computer (usually, this is drive C).


Secondary Site

A secondary site does not have a SQL Server database to store its system, package, inventory, and status information. Instead, it forwards inventory and status information to its primary site for processing and storage. It also does not have administrative tools since a secondary site must be administered through one of its parent sites. You create a secondary site from a primary site using the SMS Administrator. This primary site is known as the parent site for the secondary site. The secondary site appears directly beneath the parent site in the site hierarchy.

To create a secondary site, SMS needs an account that has specific privileges at the secondary site and the primary site must have a valid address for the secondary site. Each site must have a common protocol and connectivity.

A secondary site cannot be a parent site and you cannot attach sites beneath it. You also cannot move a secondary site to another position in the site hierarchy nor can you change its parent site. Once the secondary site is created, you can add new domains and clients to the site. Domains and clients are added to a secondary site the same way they are added to a primary site.

SMS services at the primary site connect to the secondary site and install a Bootstrap service to initiate its setup. When the services are started at the secondary site, they manage the installation of SMS components at that site. You can install a secondary site over a LAN or by using RAS from the primary site, but you cannot create a secondary site across an SNA backbone entirely from the primary site. To complete a secondary site installation over SNA, you must install the SNA Receiver and Bootstrap services on the site server for the secondary site.

Installing a Secondary Site

This section describes what happens after you add a secondary site using the SMS Administrator. This process is summarized in Figure 3.1, Secondary Site Installation.

After you have confirmed the secondary site installation and the Success message box displays the message Site creation has been initiated, the secondary site's configuration is added to the database of the current site (the parent site of the secondary site). The Hierarchy Manager detects the new secondary site in the site database and updates the addressing for the parent site so that the addressing for the new secondary site is available for use by the sender.

The Hierarchy Manager then initiates a special send request, which is sent to the Scheduler. The Scheduler creates a send request file that gives the sender instructions to install the installation directory, to install the Bootstrap service to that directory, and to start the Bootstrap service on the site server for the secondary site. The sender connects to the site server for the secondary site and carries out the actions specified by the send request.

After the Bootstrap service has confirmed that it has started at the secondary site, the Hierarchy Manager at the parent site then creates another job to send the SMS site package, which contains all the SMS site components. This job uses the regular Scheduler/sender mechanism to transfer the package to the secondary site. The Hierarchy Manager uses the SYSTEM.MAP file to determine which files to copy to the secondary site.

When the Bootstrap service receives the package, it places the package in the SMS root directory as BOOTSTRP.PK1.

Figure 3.1 Secondary Site Installation

After the Bootstrap service has confirmed that it has started at the secondary site, the Hierarchy Manager at the parent site then creates another job to send the SMS site package, which contains all the SMS site components. This job uses the regular Scheduler/sender mechanism to transfer the package to the secondary site. The Hierarchy Manager uses the SYSTEM.MAP file to determine which files to copy to the secondary site.

When the Bootstrap service receives the package, it places the package in the SMS root directory as BOOTSTRP.PK1.

At the parent site, the Hierarchy Manager creates a job to send a site control file (_INIT.CT1) to the secondary site. The site control file contains the configuration information for the secondary site.

When the Bootstrap service receives the package for the site control file, it places the package in the SMS root directory as BOOTSTRP.PK2. The Bootstrap service then verifies the integrity of the packages.

If the package files are corrupted, the Bootstrap service reports the problem to the trace log and Windows NT event log and then stops the installation process.

If the package files are valid, the Bootstrap service checks to make sure that there is enough free disk space to install the site server components.

If there is not enough disk space, the Bootstrap service reports the problem to the trace log and the Windows NT event log and then stops the installation process.

If there is enough free disk space and the package files are valid, the Bootstrap service decompresses the packages, creates the site directory structure on the site server, and places the components in the appropriate directories

The Bootstrap service then starts the Site Configuration Manager. After the Site Configuration Manager has started, the Bootstrap service stops. The Site Configuration Manager uses the site control file to complete the secondary site's installation and configuration.

As part of site configuration, the Site Configuration Manager starts all SMS services at the site.

After the site services have been started, the Site Configuration Manager creates another temporary site control file (*.CT2) that contains the actual configuration at the secondary site. The Site Configuration Manager creates a job to send the site control file back to the parent site. This job uses the regular Scheduler/sender mechanism to transfer the site control file to the parent site (for more information on how the Scheduler and sender interact, see "Collecting Inventory at a Secondary Site" later in this chapter). This process repeats each time you modify the configuration of a secondary site.

At the parent site, the Despooler places the site control file in the SITE.SRV\SITECFG.BOX directory of the SMS_SHRx share on the site server. The Hierarchy Manager at the parent site updates the site database with the actual configuration at the secondary site. When you refresh the SMS Administrator, the secondary site appears as an installed site in the Sites window. Using the Properties command from the File menu, you can view (and modify) the properties for the new secondary site.

Modifying Properties at a Secondary Site

Modifications of the secondary site's properties are initiated from the SMS Administrator and then carried out by the Hierarchy Manager at the parent site and the Site Configuration Manager at the secondary site. The Hierarchy Manager creates a job to send a site control file to the secondary site. This job uses the regular Scheduler/sender mechanism to transfer the site control file package to the secondary site.

At the secondary site, the Site Configuration Manager uses the site control file to update the secondary site's configuration. After the configuration is complete, the Site Configuration Manager creates a site control file that contains the actual configuration at the secondary site. The Site Configuration Manager creates a job to send the site control file back to the parent site. This job uses the regular Scheduler/sender mechanism to transfer the site control file to the parent site. At the parent site, the Hierarchy Manager updates the parent site's database.

Note that during primary and secondary site installation, the Hierarchy Manager and Site Configuration Manager create files called _INIT.CT1 and *.CT2, respectively. When site properties are later modified, these files are recreated using random numerical names.

Installing an SNA-linked Secondary Site

If the secondary site is connected through an SNA link (summarized in Figure 3.2, SNA-linked Secondary Site Installation), installation differs from the regular secondary site installation (summarized in Figure 3.1, Secondary Site installation), as follows:

  • You must run the SMS Setup program at the secondary site prior to adding the secondary site to its parent site. SNA Setup starts the Bootstrap and SNA Receiver services at the target site.
  • The Hierarchy Manager does not send a job to start the Bootstrap service at the secondary site (because the SNA Setup program starts it).
  • Incoming packages at both primary and secondary sites go through the SNA Receiver. The SNA Receiver at the secondary site acknowledges receipt of incoming packages, but does not check to confirm that they have been processed correctly by the Bootstrap service.

Secondary Site Component Upgrade

This section describes what happens after you add a component or upgrade the primary site directly above the secondary site, using the SMS Setup program. This process is summarized in Figure 3.3, Secondary Site Component Upgrade.

After you have confirmed the secondary site update, the SMS Setup program adds an upgrade instruction in the site database for all secondary sites directly beneath the current site. The Hierarchy Manager service detects this instruction and waits for all these secondary sites to be in the active state. The Hierarchy Manager will not begin the upgrade process if any secondary sites are still in the process of being created or deleted.

When all secondary sites are active, the Hierarchy Manager creates a system job for each site. The Hierarchy Manager creates a job (a system job with the comment Bootstrap Job for <sitecode> where sitecode is the site code for the secondary site to be upgraded) to send to each secondary site to install and start the SMS Upgrade Bootstrap service at each secondary site. The bootstrap job is phase 1 of the upgrade.

Note

For a secondary site connected to its parent site using the SNA Sender, the bootstrap job also installs and starts an Upgrade SNA Receiver service. This service is used temporarily so that the primary site can continue to send site upgrade jobs to the site during the removal and upgrade of the existing SNA Receiver service.

Figure 3.2 SNA-linked Secondary Site Installation

Figure 3.3 Secondary Site Component Upgrade

At each secondary site server, the Upgrade Bootstrap service shuts down the site in preparation for the upgrade. All SMS services are stopped except the Upgrade Bootstrap service. At the primary site, you will not be able to edit Site Properties dialog box for these sites while they are in upgrade status (in the Sites window, the sites will have an under construction icon and their Site Properties dialog boxes will display the site upgrade phase).

After the Upgrade Bootstrap service has confirmed that it has started at the secondary site, the Hierarchy Manager at the parent site then creates another job (a system job with the comment Site Install Job for <sitecode> where sitecode is the site code for the secondary site to be upgraded) to send the SMS site package, which contains all the SMS site components. This job uses the regular Scheduler/sender mechanism to transfer the package to the secondary site. The Hierarchy Manager uses the SYSTEM.MAP file to determine which files to copy to the secondary site. The site install job is phase 2 of the upgrade.

When the Upgrade Bootstrap service receives the package, it places the package in the SMS root directory as BOOTSTRP.PK1.

At the parent site, the Hierarchy Manager creates a job (a system job with the comment Site Control Job for <sitecode> where sitecode is the site code for the secondary site to be upgraded) to send a site control file (_INIT.CT1) to the secondary site. The site control file contains the configuration information for the secondary site. The site control job is phase 3 of the upgrade.

When the Upgrade Bootstrap service receives the package for the site control file, it places the package in the SMS root directory as BOOTSTRP.PK2. The Upgrade Bootstrap service then verifies the integrity of the packages.

If the package files are corrupted, the Upgrade Bootstrap service reports the problem to the trace log and the Windows NT event log and then stops the installation process.

If the package files are valid, the Upgrade Bootstrap service checks to make sure that there is enough free disk space to install the site server components.

If there is not enough disk space, the Upgrade Bootstrap service reports the problem to the trace log and the Windows NT event log and then stops the installation process.

If there is enough free disk space and the package files are valid, the Upgrade Bootstrap service decompresses the packages, creates the site directory structure on the site server, and places the components in the appropriate directories.

If the Upgrade Bootstrap service does not receive valid packages or cannot decompress the packages within 48 hours, it will attempt to restart the site with the original site components. After the site's SMS services have been restarted, the Hierarchy Manager will report its configuration back to the parent site. If the site upgrade has taken longer than 48 hours, you should verify that the site has been updated or that the components have been added to the site. If the upgrade has failed, you can try again by upgrading the primary site or installing the new software component using the SMS Setup program. You can also use the PREINST program (the executable version of the Hierarchy Manager) to force an upgrade of a specific secondary site.

Then Upgrade Bootstrap service starts the Site Configuration Manager. After the Site Configuration Manager has started, the Upgrade Bootstrap service stops. The Site Configuration Manager uses the site control file to complete the secondary site's installation and configuration.

As part of the site configuration, the Site Configuration Manager starts all SMS services at the site.

After the site services have been started, the Site Configuration Manager creates another temporary site control file (*.CT2) that contains the actual configuration at the secondary site. The Site Configuration Manager creates a job to send the site control file back to the parent site. This job uses the regular Scheduler/sender mechanism to transfer the site control file to the parent site (for more information on how the Scheduler and Sender interact, see "Collecting Inventory at a Secondary Site" later in this chapter). This job is phase 4 of the upgrade.

At the parent site, the Despooler places the site control file in the SITE.SRV\SITECFG.BOX directory of the SMS_SHRx share on the site server. The Hierarchy Manager at the parent site updates the site database with the actual configuration at the secondary site. When you refresh the SMS Administrator, the secondary site appears as an installed site in the Sites window. Using the Properties command from the File menu, you can view (and modify) the properties for the new secondary site.

Secondary Site Removal

This section describes what happens after you delete a secondary site using the SMS Administrator. This process is summarized in Figure 3.4, Secondary Site Removal.

After you have confirmed the secondary site deletion and the Success message box displays the message Site creation has been initiated, the SMS Administrator adds a deletion instruction in the site database for the secondary site.

When the Hierarchy Manager detects this instruction, it creates a job (a system job with the comment Bootstrap Job for <sitecode> where sitecode is the site code for the secondary site to be removed) to send to the secondary site to install and start the Bootstrap service at that secondary site.

At the secondary site, the Site Configuration Manager installs the Bootstrap service, which then takes over removal of the site.

At the primary site, when the bootstrap job has completed, the Hierarchy Manager removes the site from the site database.

The Hierarchy Manager then forwards the site deletion information to its own parent site, which removes the site from its database. The site deletion information is then forwarded to its parent site, and so on. The site deletion is reported all the way up to the central site.

If the secondary site removal has failed, the site may reappear at the parent site, since it may continue reporting. If this happens, you can delete it again. Or you can use the SMS Setup program at the secondary site server.

At the secondary site server, you can view the BOOTSTRP.LOG file (in the root of the drive containing the SMS root directory) for a record of the actions and errors reported by the Bootstrap service.

Note

If you delete the site icon twice in the Sites window of the SMS Administrator and the site has already been removed, the second bootstrap job will not be able to complete, because the secondary site no longer exists. If this happens, you can cancel or delete the second bootstrap job and the Hierarchy Manager will remove the site from the site database.

Figure 3.4 Secondary Site Removal


General Management Within a Site

The following section describe how SMS logon servers are installed, how clients are installed, and how SMS identifies and tracks computers.

SMS Logon Server Component Installation

When you add a domain to your SMS site (using the Domains dialog box), the Site Configuration Manager service enumerates all detected (or specified) logon servers in the domain and ensures that the SMS components used to support that domain's clients are installed on each logon server. (Note that the site server's domain is added during primary site installation.)

Windows NT, LAN Manager, and LAN Server Domains

To add a Windows NT, LAN Manager, or LAN Server domain, the Site Configuration Manager:

  • Creates the SMS root directory on the logon server NTFS drive with the most available space and shares the SMS root directory as SMS_SHRx (where x is the drive letter where the SMS root directory is installed). If an NTFS drive is not available, the Site Configuration Manager creates SMS_SHRx on the largest non-NTFS drive.
  • Creates the LOGON.SRV directory as a subdirectory of the SMS root directory and shares it as SMS_SHR.
  • Copies all logon server components to the LOGON.SRV directory.
  • On computers running Windows NT Server, installs and starts the Inventory Agent for Windows NT to collect inventory on the logon server. On LAN Manager version 2.x servers, installs and starts the Inventory Agent for OS/2.
  • On computers running Windows NT Server, installs and starts the Package Command Manager for Windows NT to collect inventory on the logon server.
  • On computers running Windows NT Server, installs and starts the Client Configuration Manager service to process *.CCR files from clients running Windows NT. The Client Configuration Manager uses information in the *.CCR files to configure SMS services on clients running Windows NT.
  • Adds the SMSLS batch file to the replication (REPL$) and NETLOGON shares, if the Automatically Configure Workstation Logon Scripts option is enabled. The Site Configuration Manager also adds the SMSLS batch file to all user profiles. If a user has an existing logon script, it adds a call to the SMSLS batch file to the script. If a user has no logon script, it adds the SMSLS batch file to the user's profile.

If the Use All Detected Servers option is enabled, the Site Configuration Manager monitors the domain for any new servers that have been added to the domain, including servers that were temporarily off the network and are now back on. When it detects a new server, the Site Configuration Manager copies files to the new server.

NetWare Domains

In NetWare domains, the Site Configuration Manager installs logon server components on all detected (or specified) logon servers. The Site Configuration Manager places files on the NetWare volume with the most free space. If the Automatically Configure Workstation Logon Scripts option is enabled, it modifies the system logon script for the logon server to run the SMS Client Setup program and the Inventory Agent for MS-DOS.

If the Use All Detected Servers option is enabled, the Site Configuration Manager enumerates all NetWare file servers on the network within 16 router hops and installs the logon server components on these servers. After the initial installation of the domain, the Site Configuration Manager continues to monitor the network for new file servers and adds logon server components to any it detects.

Clients

The following sections describe how clients are installed and how SMS Client Setup works. This section applies to all SMS clients except for SMS logon servers and Macintosh clients. Installation of SMS logon servers is described in "SMS Logon Server Component Installation" earlier in this chapter. Macintosh clients use the Apple® Installer to set up SMS. For more information on how Macintosh clients are installed, see the SMS version 1.2 product documentation.

Client Installation Process

There are three ways that clients are added to an SMS site:

  • A user at a client can connect to an SMS logon server in an SMS-enabled domain and run the RUNSMS batch file. This file calls the SMS Client Setup program (CLI_NT.EXE, CLI_OS2.EXE, or CLI_DOS.EXE), which copies SMS files to the client and configures SMS client components. The RUNSMS batch file also calls the Inventory Agent, which collects inventory if the appropriate inventory frequency interval has passed.
  • You can use the Automatically Configure Workstation Logon Scripts option to modify logon scripts for all users. This runs the SMSLS.BAT file when a user logs on to the network.
  • For Windows NT, LAN Manager, and LAN Server domains, you can manually add the SMSLS batch file to a user's logon script. For NetWare domains, the system login script or individual user login scripts can be modified on NetWare servers to run the SMSLS.SCR script.

When you make a manual connection to the SMS_SHR of an SMS logon server and run the RUNSMS batch file, the client is added to the SMS domain of the SMS logon server where you ran the RUNSMS batch file command.

When you run the SMSLS batch file as part of a logon script, the SETLS program (which is run from within the SMSLS batch file) can read SMSLS.INI to locate a server domain where the client should be added. SMSLS.INI enables you to use existing configurations on a client to map the client to a specific SMS domain and site.

SETLS evaluates SMSLS.INI from top to bottom and uses the first successful match in the mapping list. After it finds a match, it uses the mapped domain as the client's SMS domain and attempts to find a random server within that domain. SETLS then connects to that server and runs SMS Client Setup and the Inventory Agent. If SMSLS.INI is not found, SETLS runs these programs on the current SMS logon server.

How SMS Client Setup Works

The SMS Client Setup program is called by the RUNSMS (or SMSLS) batch file after it determines the client's operating system. There are three versions of the SMS Client Setup program that support computers running Windows NT, Windows 95, Windows version 3.1, Windows for Workgroups 3.11, MS-DOS, and OS/2. Note that Macintosh computers use the Apple Installer program to set up and configure the client.

For computers running Windows NT, the SMS Client Setup program is CLI_NT.EXE. There are three subdirectories beneath the LOGON.SRV directory to support the three microprocessor types supported by SMS for Windows NT: ALPHA.BIN, MIPS.BIN, and X86.BIN. Each subdirectory contains the SMS Client Setup program (CLI_NT.EXE) for each microprocessor type running Windows NT.

For computers running MS-DOS, Windows version 3.1, Windows for Workgroups 3.11, and Windows 95, the SMS Client Setup program is CLI_DOS.EXE. The X86.BIN subdirectory beneath the LOGON.SRV directory contains the CLI_DOS.EXE program.

For computers running OS/2, the SMS Client Setup program is CLI_OS2.EXE. The X86.BIN subdirectory beneath the LOGON.SRV directory contains the CLI_OS2.EXE program.

SMS Client Setup General Actions

SMS Client Setup performs the following actions:

1. Determines whether SMS.INI exists on the client.

If SMS Client Setup cannot find SMS.INI, SMS Client Setup considers this a new installation.

2. Determines the language and operating system.

The SMS Client Setup program must detect the language used on the computer to install the files appropriate for the language on that computer. SMS Client Setup also needs to know the operating system so that the appropriate copy-list file and modification file are installed and configured properly. On computers running Windows NT, the microprocessor type must also be detected so the files for the appropriate microprocessor type are installed.

If SMS Client Setup detects a different operating system from the one recorded in the OS entry of the [SMS] section in SMS.INI, SMS Client Setup displays a warning message and stops. SMS currently supports one operating system per computer. To force the SMS components to be upgraded to a new operating system, you must run SMS Client Setup in upgrade mode or run UPGRADE.BAT from an SMS logon server.

3. Reads the copy-list file on the SMS logon server for the location of the SMS client component files for the computer's operating system and language.

4. Opens the appropriate language DLL so that messages can be displayed with the language appropriate for the client.

5. Reads DOMAIN.INI (from the SMS logon server) to update information in the SMS.INI file.

6. Performs the required actions depending on the mode that SMS Client Setup is running in.

For more information, see the following sections.

Installation Mode

If installation is required, SMS Client Setup performs the following steps:

1. Performs the checks listed in the preceding section.

2. Attempts to create a new SMS ID for the computer using the *.UID file in the SMS logon server's LOGON.SRV\SMSID directory.

3. Finds the local drive with the most free disk space.

SMS client components are installed on this drive if the /d:drive parameter is not specified.

4. Detects the computer's microprocessor type so that the files that are appropriate for the microprocessor type are installed.

5. Determines the network type using the NetworkType entry specified in the LOGON.SRV\DOMAIN.INI file on the SMS logon server.

This entry specifies which network operating system is used by the SMS logon server.

6. Creates the SMS.INI file in the root of the first local hard disk drive (usually, this is drive C).

7. Decides which files to download using the CL_x.TXT file and the Components entry in the [SMS] section of the DOMAIN.INI file.

SMS Client Setup tries to copy files to the drive with the most free space, unless you use the /d:drive option to specify another drive. If space is unavailable on the drive you specify, SMS Client Setup will not complete the installation.

If it cannot copy down one or more files, SMS Client Setup writes the names of these files to the FilesNotDownloaded entry in the [Workstation Status] section of the SMS.INI file.

8. Creates a local copy-list file (CL_x.TXT).

Copy-list file | Operating system
CL_NT.TXT | Windows NT
CL_W95.TXT | Windows 95
CL_WIN.TXT | Windows 3.1 and Windows for Workgroups 3.11
CL_OS2.TXT | OS/2
CL_DOS.TXT | MS-DOS

9. Uses the [SMS] section in the DOMAIN.INI file as well as the appropriate configuration file (CL_WIN.MOD, CL_DOS.MOD, and so on) to see what modifications it needs to make at the client.

MOD file | Operating system | Logon server location
CL_NT.MOD | Windows NT (Alpha) | LOGON.SRV\ALPHA.BIN\language_id
CL_NT.MOD | Windows NT (MIPS) | LOGON.SRV\MIPS.BIN\language_id
CL_NT.MOD | Windows NT (x86) | LOGON.SRV\X86.BIN\language_id
CL_W95.MOD | Windows 95 | LOGON.SRV\X86.BIN\language_id
CL_WIN.MOD | Windows 3.1 and Windows for Workgroups 3.11 | LOGON.SRV\X86.BIN\language_id
CL_OS2.MOD | OS/2 | LOGON.SRV\X86.BIN\language_id
CL_DOS.MOD | MS-DOS | LOGON.SRV\X86.BIN\language_id

10. Modifies the system configuration to add the SMS components. How this is done depends on the type of client.

For clients running Windows NT:

  • Uses information in CL_NT.MOD to create SMSRUN32.INI in the MS\SMS\DATA directory. This file specifies which SMS applications to start automatically and which program groups to create.
  • Starts SMSRUN32.EXE. SMSRUN32.EXE reads SMSRUN32.INI. SMS Client Setup modifies the HKEY_CURRENT_USER\Software \Microsoft\WindowsNT\CurrentVersion\Windows\Load value in the Windows NT registry to run SMSRUN32.EXE. SMSRUN32.EXE runs the programs listed in the [Startup] section of SMSRUN32.INI. Note that SMSRUN32.EXE is only started by SMS Client Setup when it cannot find SMSRUN32.EXE in the Load value of the HKEY_CURRENT_USER \Software\Microsoft\WindowsNT\CurrentVersion\Windows key.

For clients running Windows 95:

  • Uses information in CL_W95.MOD to create SMSRUN16.INI in the MS\SMS\DATA directory. This file specifies which SMS applications to start automatically and which Start menu items to create.
  • Modifies WIN.INI to run SMSRUN16.EXE from the LOAD= line in the [Windows] section of the WIN.INI file. From then on, when Windows is started, SMSRUN16 runs and uses information in SMSRUN16.INI to decide which applications to start and which Start menu items to set up.
  • Creates MS\SMS\DATA\CLIENT.BAT and modifies AUTOEXEC.BAT to run CLIENT.BAT prior to running Windows. The call to CLIENT.BAT is inserted at the end of the AUTOEXEC.BAT file.
  • If the client is to be configured for remote troubleshooting, SMS Client Setup modifies these settings in the [386Enh] section of the SYSTEM.INI file: Device=vuser.386 and NetHeapSize (sets it to 48 if the current value is less than 48; keeps the current setting if the value is greater than 48).
  • If the client is to be configured for Program Group Control, SMS Client Setup:
  • Modifies these settings in the [386Enh] section of the SYSTEM.INI file: Device=vsmsnet.vxd and Device=smsroutr.vxd.
  • Installs and configures the SMS Naming Network Provider (NNP) in the registry by adding the entry SMS Naming Network Provider with a value of NNP.EXE to the key HKEY_LOCAL_MACHINE\Software \Microsoft\Windows\CurrentVersion\RunServices.

For clients running Windows version 3.1 and Windows for Workgroups:

  • Uses information in CL_WIN.MOD to create SMSRUN16.INI in the MS\SMS\DATA directory. This file specifies which SMS applications to start automatically and which program groups to create.
  • Modifies WIN.INI to run SMSRUN16.EXE from the LOAD= line in the [Windows] section of the WIN.INI file. From then on, when Windows is started, SMSRUN16 runs and uses information in SMSRUN16.INI to decide which applications to start and which program groups to set up.
  • Creates MS\SMS\DATA\CLIENT.BAT and modifies AUTOEXEC.BAT to run CLIENT.BAT prior to running Windows (SMS Client Setup looks for the win command on each line).
  • If the client is to be configured for remote troubleshooting, SMS Client Setup:
  • Modifies these settings in the [386Enh] section of the SYSTEM.INI file: Device=vuser.386 and NetHeapSize (sets it to 56 if the current value is less than 56; keeps the current setting if the value is greater than 56).

For clients running only MS-DOS (that is, MS-DOS without Windows version 3.1 or Windows for Workgroups installed on the computer):

  • Creates MS\SMS\DATA\CLIENT.BAT and modifies AUTOEXEC.BAT to run CLIENT.BAT.
  • If remote troubleshooting is to be installed and automatically started, SMS Client Setup modifies CLIENT.BAT to run USERTSR.EXE or USERIPX.EXE, depending on the network type.
  • Modifies CLIENT.BAT to automatically start Package Command Manager and the MIF Entry program, if appropriate.

For clients running OS/2:

  • Uses information in CL_OS2.MOD to create SMSRUN16.INI in the MS\SMS\DATA directory. This file specifies which SMS applications to start automatically and which program groups to create.
  • Modifies WIN.INI to run SMSRUN16.EXE from the LOAD= line in the [Windows] section of the WIN.INI file. From then on, when a Windows-based OS/2 session is started, SMSRUN16 runs and uses information in SMSRUN16.INI to decide which applications to start and which program groups to set up.
  • Creates MS\SMS\DATA\CLIENT.BAT and modifies AUTOEXEC.BAT to run CLIENT.BAT prior to running a Windows-based OS/2 session (SMS Client Setup looks for the win command on each line).
  • Adds SMSOS2AG.EXE to the STARTUP.CMD.

Note

When SMS Client Setup modifies system *.INI files, it comments out previous entries, by placing ;SMS in front of those entries. If the client is being removed, SMS Client Setup removes the comment to return the client to its previous state.

11. On computers running Windows NT, SMS Client Setup evaluates whether the client has the version of the operating system appropriate for the SMS services to be installed. Then it creates a *.CCR file on the SMS logon server for the Client Configuration Manager. For more information about how SMS services are installed on computers running Windows NT, see "How SMS Client Setup Installs SMS Client Services on Computers Running Windows NT" later in this chapter.

12. Writes INSTALLED in the SetupPhase entry of the [Local] section of the SMS.INI file, on all clients.

Removal Mode

When SMS Client Setup is started using the /r switch to remove a client (or if the DEINSTAL.BAT or DEINSTAL.CMD batch files are run), SMS Client Setup performs the following for each type of operating system.

For clients running only MS-DOS

1. Performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

2. Removes the existing SMS component files. It also removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

For clients running Windows version 3.1, Windows for Workgroups, Windows 95, and Windows NT:

1. Performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

2. Writes DEINSTALL in the SetupPhase entry of the [LOCAL] section of SMS.INI and exits.

3. Depending on the operating system, the user must either restart Windows or log off and back on to the network.

For computers running Windows version 3.1 and Windows for Workgroups, the user must start or restart Windows to complete the removal.

For computers running Windows 95 and Windows NT, at the computer, the user must log off and log on to the network.

4. The SMSRUN program starts and checks the SetupPhase entry.

5. SMSRUN starts the SMSSVR program with the /c switch, which tells SMSSVR to call SMS Client Setup to complete the removal, and then SMSRUN exits.

6. SMSSVR starts SMS Client Setup with the /k switch, which tells SMS Client Setup that it can remove SMS component files to complete the removal.

7. SMS Client Setup removes the existing SMS component files. It also removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

8. On computers running Windows NT, SMS Client Setup creates a *.CCR file on the SMS logon server for the Client Configuration Manager so that the Client Configuration Manager can remove the SMS services from the client. For more information about how SMS services are removed from computers running Windows NT, see "How SMS Client Setup Installs SMS Client Services on Computers Running Windows NT" later in this chapter.

For clients running OS/2:

1. The user should close all Windows-based OS/2 sessions.

2. The user runs CLI_OS2 /r or DEINSTAL.CMD from an SMS logon server.

3. SMS Client Setup performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

4. Writes DEINSTALL in the SetupPhase entry of the [LOCAL] section of SMS.INI, and then exits.

5. The user starts a new Windows-based OS/2 session.

6. The SMSRUN program starts and checks the SetupPhase entry.

7. SMSRUN starts the SMSSVR program with the /c switch, which tells SMSSVR to call SMS Client Setup to complete the removal, and then SMSRUN exits.

8. SMSSVR starts SMS Client Setup with the /k switch, which tells SMS Client Setup to remove SMS component files to complete the removal.

9. SMS Client Setup Removes the existing SMS component files. It also removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

Upgrade Mode

When SMS Client Setup is started using the /u switch to upgrade a client (or if the UPGRADE.BAT or UPGRADE.CMD batch files are run), SMS Client Setup performs the following for each type of operating system.

For clients running only MS-DOS:

1. Performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

2. Detects the computer's microprocessor type so that the files that are appropriate for the microprocessor type are installed.

3. Determines the network type using the NetworkType entry specified in the LOGON.SRV\DOMAIN.INI file on the SMS logon server.

This entry specifies which network operating system is used by the SMS logon server.

4. Compares the Components and AutoStart entries in the [SMS] section of the DOMAIN.INI file on the SMS logon server with the InstalledComponents and AutoStartComponents entries in the [WorkstationStatus] section of the SMS.INI file on the client.

By performing this comparison, SMS Client Setup determines which existing SMS client components need to be added, removed, or upgraded.

5. Removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

6. Upgrades the SMS components on the client by removing unneeded components, installing new ones, or replacing existing ones.

7. Modifies the system configuration to configure the set of SMS components specified by the upgrade.

For more information about how the system configuration is modified for the installation of SMS components, see step 10 in "Installation Mode" earlier in this chapter.

8. If SMS Client Setup cannot install a file, it will try again the next time SMS Client Setup runs.

For clients running Windows version 3.1, Windows for Workgroups, Windows 95, and Windows NT:

1. Performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

2. Detects the computer's microprocessor type so that the files that are appropriate for the microprocessor type are installed.

3. Determines the network type using the NetworkType entry specified in the LOGON.SRV\DOMAIN.INI file on the SMS logon server.

This entry specifies which network operating system is used by the SMS logon server.

4. Writes UPGRADE in the SetupPhase entry of the [LOCAL] section of SMS.INI, and then exits.

5. Depending on the operating system, the user must either restart Windows or log off and back on to the network.

For computers running Windows version 3.1 and Windows for Workgroups, the user must start or restart Windows to complete the upgrade.

For computers running Windows 95 and Windows NT, at the computer, the user must log off and log on to the network.

6. The SMSRUN program starts and checks the SetupPhase entry.

7. SMSRUN starts the SMSSVR program with the /c switch, which tells SMSSVR to call SMS Client Setup to complete the upgrade, and then SMSRUN exits.

8. SMSSVR starts SMS Client Setup with the /k switch, which tells SMS Client Setup that it can remove SMS component files to complete the upgrade. SMSSVR waits for SMS Client Setup to complete the upgrade.

9. Compares the Components and AutoStart entries in the [SMS] section of the DOMAIN.INI file on the SMS logon server with the InstalledComponents and AutoStartComponents entries in the [WorkstationStatus] section of the SMS.INI file on the client.

By performing this comparison, SMS Client Setup determines which existing SMS client components need to be added, removed, or upgraded.

10. Removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

11. Upgrades the SMS components on the client by removing unneeded components, installing new ones, or replacing existing ones.

12. Modifies the system configuration to configure the set of SMS components specified by the upgrade.

For more information about how the system configuration is modified for the installation of SMS components, see step 10 in "Installation Mode" earlier in this chapter.

13. If SMS Client Setup cannot install a file, it will try again the next time SMS Client Setup runs.

14. On computers running Windows NT, SMS Client Setup evaluates whether the client has the version of the operating system appropriate for the SMS services to be installed or upgraded. Then it creates a *.CCR file on the SMS logon server for the Client Configuration Manager. For more information about how SMS services are installed or upgraded on computers running Windows NT, see "How SMS Client Setup Installs SMS Client Services on Computers Running Windows NT" later in this chapter.

15. SMSSVR uses the SMSRUN16.INI/SMSRUN32.INI file to set up the SMS Client program group and start SMS components that are configured to start automatically, and then SMSSVR exits.

For clients running OS/2:

1. The user should close all Windows-based OS/2 sessions.

2. The user runs CLI_OS2 /u or UPGRADE.CMD from an SMS logon server.

3. SMS Client Setup performs the checks listed in "SMS Client Setup General Actions" earlier in this chapter.

4. Detects the computer's microprocessor type so that the files that are appropriate for the microprocessor type are installed.

5. Determines the network type using the NetworkType entry specified in the LOGON.SRV\DOMAIN.INI file on the SMS logon server.

This entry specifies which network operating system is used by the SMS logon server.

6. Writes UPGRADE in the SetupPhase entry of the [LOCAL] section of SMS.INI, and then exits.

7. The user starts a new Windows-based OS/2 session.

8. The SMSRUN program starts and checks the SetupPhase entry.

9. SMSRUN starts the SMSSVR program with the /c switch, which tells SMSSVR to call SMS Client Setup to complete the upgrade, and then SMSRUN exits.

10. SMSSVR starts SMS Client Setup with the /k switch, which tells SMS Client Setup that it can remove SMS component files to complete the upgrade. SMSSVR waits for SMS Client Setup to complete the upgrade.

11. Compares the Components and AutoStart entries in the [SMS] section of the DOMAIN.INI file on the SMS logon server with the InstalledComponents and AutoStartComponents entries in the [WorkstationStatus] section of the SMS.INI file on the client.

By performing this comparison, SMS Client Setup determines which existing SMS client components need to be added, removed, or upgraded.

12. Removes the SMS configurations from system files and restores the previous setting that existed before SMS was installed.

13. Upgrades the SMS components on the client by removing unneeded components, installing new ones, or replacing existing ones.

14. Modifies the system configuration to configure the set of SMS components specified by the upgrade.

For more information about how the system configuration is modified for the installation of SMS components, see step 10 in "Installation Mode" earlier in this chapter.

15. If SMS Client Setup cannot install a file, it will try again the next time SMS Client Setup runs.

16. SMSSVR uses the SMSRUN16.INI file to set up the SMS Client program group and start SMS components that are configured to start automatically, and then SMSSVR exits.

How SMS Client Setup Installs SMS Client Services on Computers Running Windows NT

On a computer running Windows NT, SMS Client Setup runs via a logon script or batch file in the security context of the user logged on to that computer. For SMS 1.2, SMS services and device drivers must be installed and configured (as well as modifications to the registry) for the Client Inventory service, Remote Control Agent service, and SNMP Event to Trap Translator. However, service and device driver installation and configuration require Administrator privilege (in addition, some of the SMS services must also run in the context of a service account with Administrator privilege). In many cases, the user who logs on to a computer does not have this privilege. To enable users to log on to their computer with the appropriate level of access assigned to them and enable SMS to install and configure SMS services on clients running Windows NT, SMS 1.2 has enhancements to SMS Client Setup as well as two additional components (the Client Configuration Manager service and CLIMONNT.EXE).

This section describes how the following SMS client services and components are installed on computers running Windows NT:

  • Remote Control Agent
  • Client Inventory
  • SNMP Event to Trap Translator
How SMS client services are installed, upgraded, and removed:

1. As described in "How SMS Client Setup Works" earlier in this chapter, SMS Client Setup determines which SMS client components need to be added, removed, or upgraded.

2. SMS Client Setup then evaluates whether the client has the version of the operating system appropriate for the SMS services to be installed or upgraded:

  • The Remote Control Agent service requires Windows NT version 3.51 or later. If the computer is running an earlier version of the Windows NT operating system, SMS Client Setup will not install this component.
  • The Client Inventory service is only installed if the SMS_INVENTORY _AGENT_NT service (the version of the Inventory Agent service that runs on SMS logon servers running Windows NT Server) is not already installed.

3. SMS Client Setup adds keys and values to the client's registry to specify configuration data required by the Client Configuration Manager to install, upgrade, or remove SMS client services.

SMS Client Setup adds configuration data in the following key:

HKEY_LOCAL_MACHINE\Software\Microsoft\SMS\Client Services

4. If any components needed to be installed, upgraded, or removed, SMS Client Setup creates a client configuration request file (sms_id.CCR where sms_id is the SMS ID for the computer requesting a configuration change) on the current SMS logon server in the LOGON.SRV\CCR.BOX directory.

An sms_id.CCR file is an ASCII text file used to notify the Client Configuration Manager that a particular client needs a configuration change.

5. If the SMS logon server is a server running LAN Manager or LAN Server, the Maintenance Manager periodically collects the .CCR files from the LOGON.SRV\CCR.BOX directory of the SMS logon server and moves them to the LOGON.SRV\CCR.BOX directory of the site server.

The Client Configuration Manager is available only on SMS logon servers and site servers running Windows NT Server. This means that the Maintenance Manager must move the .CCR files on servers running LAN Manager and LAN Server to the site server for processing.

6. At the SMS logon server (or the site server if the .CCR file was collected from an SMS logon server running LAN Manager or LAN Server), the Client Configuration Manager has a CCR processing thread that waits for .CCR files in the LOGON.SRV\CCR.BOX directory and processes the .CCR files.

If the .CCR file was moved to the site server, the Client Configuration Manager service on the site server processes the .CCR file. In this case, connectivity between the site server and the client is required.

7. The CCR processing thread reads the .CCR file, connects to the target client registry, and checks whether it has access rights to the computer and its registry (that is, whether the SMS Service Account has access).

8. The CCR processing thread reads the client's registry to retrieve information needed to install, configure, or remove each SMS component (Remote Control Agent service, SNMP Event to Trap Translator, and Client Inventory service).

9. For each SMS component, the CCR processing thread performs the required configuration change by installing or removing services, changing service parameters, and so on.

10. For each SMS component, the CCR processing thread modifies the appropriate values within the Client Services key of the client's registry to reflect the new configuration.

11. If the CCR processing thread completes the configuration requested by a .CCR file, it deletes the .CCR file.

12. If the CCR processing thread cannot complete the configurations requested by a .CCR file, it performs one of the following actions:

  • If a .CCR file for the same target computer already exists in the LOGON.SRV\CCR.BOX\RETRY directory, the thread updates the CCR in the RETRY directory with the values for the .CCR file in the CCR.BOX directory. After updating the .CCR file in the RETRY directory, the thread deletes the .CCR file in the CCR.BOX directory.
  • If a .CCR file for the same target computer does not exist in the RETRY directory, the thread moves the .CCR file to that directory.

If the Error Reporting Delay time has passed and an event MIF file has not been created for this .CCR file, the Client Configuration Manager writes an event MIF file that reports the following:

  • Last error (for example, access denied).
  • Name of computer where Client Configuration Manager processed the .CCR file.
  • Name of target computer.
  • Date and time of the first and last attempt.

The Client Configuration Manager has a separate CCR retry thread to process .CCR files placed in the RETRY subdirectory. The CCR retry thread attempts to perform the incomplete configurations by periodically reprocessing the .CCR files in the RETRY directory. Note that the processing of the .CCR files by this thread is the same as the CCR processing thread. For each .CCR file, the CCR retry thread will continue retrying periodically until the retry duration expires for the .CCR file. If an event MIF file was reported for a .CCR file, the CCR retry thread creates an event MIF file for the .CCR file, reporting that the .CCR file has successfully been processed.

13. If a configuration change performed by Client Configuration Manager requires the client to be restarted, the Client Monitor program running on the client displays a message stating that a restart is required to finish the configuration of the SMS client components and prompts the user to restart or not.


Inventory

The following sections describe how inventory is collected and processed in SMS.


Collecting Inventory at Sites

The following sections describe how inventory is collected and reported at primary and secondary sites.

Collecting Inventory at a Primary Site

This section describes how SMS collects and uses inventory information at a primary site. The inventory collection process varies depending on your network operating system (Windows NT, LAN Manager, NetWare, or Macintosh). This process is summarized in the Figure 3.5, Collecting Inventory at a Primary Site.

At each SMS computer, the Inventory Agent scans and reports inventory.

At clients (such as computers running MS-DOS, Windows 3.1, Windows for Workgroups 3.11, OS/2, Macintosh, Windows 95, and Windows NT Workstation), the Inventory Agent runs in the following ways:

  • If the Automatically Configure Workstation Logon Scripts feature has been set up for the SMS domain containing the client, the Inventory Agent program is started from the logon script when the user at the client logs on to the network.
  • If the user connects to the SMS_SHR on an SMS logon server and runs the RUNSMS batch file, the Inventory Agent is started.

When the Inventory Agent runs on a client, the Inventory Agent scans the client for software (specified by the PACKAGE.RUL file) and hardware. Note that there are five versions of the Inventory Agent program for clients: INVDOS, INV32CLI, INVWIN32, INVOS2, and INVMac. The Inventory Agent checks its inventory scan interval (the inventory scan interval for hardware and software is set in the Inventory dialog box from the Site Properties dialog box). If the interval has elapsed, the Inventory Agent scans for inventory.

The Inventory Agent is installed as a service on all computers running Windows NT and on servers running LAN Manager. The Inventory Agent service wakes up every 24 hours to check the inventory scan interval, and takes inventory if the interval has elapsed.

Figure 3.5 Collecting Inventory at a Primary Site

On SMS servers (site servers, SMS logon servers, or helper servers) running Windows NT Server and LAN Manager, the Inventory Agent (INVWIN32.EXE) is installed and run as a service. This service is run using the SMS Service Account, not the user's account. This service may run even when no user is logged on to the network. When this service takes inventory, it places the inventory file on an appropriate SMS logon server for processing.

On Windows NT-based computers that are not SMS servers, SMS installs a different version of the Inventory Agent service (INV32CLI.EXE). This service ensures that inventory is reported periodically, even if a user does not explicitly run SMS Client Setup. This service runs using the local system account, which means that it can take inventory even when no user is logged on to the computer, and that it can gather information that cannot be obtained when running in the user's context. The service stores the inventory file locally.

How SMS Modifies Logon Scripts

When you set up the Automatically Configure Workstation Logon Scripts feature, SMS modifies the logon scripts for each SMS domain in the site.

How SMS modifies logon scripts depends on the network operating system of the domain.

Windows NT and LAN Manager Domains

SMS uses the Directory Replicator service to place the SMSLS batch file and the SETLS utilities on the SMS logon server shares (NETLOGON) of the SMS logon servers in the site's domains. SMS modifies the logon scripts for users at the site's domains (for users who have existing logon scripts) or sets the users' logon scripts to the SMSLS batch file (for users who do not have existing logon scripts). When the SMSLS batch file is run in a logon script, the SMSLS batch file first runs the slow network detection program (NETSPEED.COM). The SMSLS batch file then runs the SMS Client Setup program to install SMS components on the client and the Inventory Agent to collect inventory for a client from an SMS domain's logon server.

NetWare Domains

SMS modifies the system login scripts for each SMS logon server in the site's NetWare domains. SMS adds lines to the script that run the SMSLS.SCR script, which runs the slow network detection program (NETSPEED.COM), SMS Client Setup, and Inventory Agent programs.

A companion program, the Client Monitor (CLIMONNT.EXE), copies the inventory files to an SMS logon server. This program runs in the user's context, and therefore can only copy inventory files to the SMS logon server when the user is logged on to the network.

For more information about how SMS collects inventory from computers running Windows NT, see "Collecting Inventory from Computers Running Windows NT" later in this chapter.

On servers running NetWare, the Maintenance Manager on the site server scans the NetWare server and reports the inventory as a text MIF file to the site server's SITE.SRV\DATALOAD.BOX\DELTAMIF.COL where the MIF file is processed by the Inventory Data Loader.

The Inventory Agent program reports the inventory for the client by creating a RAW Inventory Agent file (*.RAW) and placing this file in the INVENTRY.BOX directory of the SMS_SHR share on the client's SMS logon server.

For NetWare servers, the file is placed in the LOGON.SRV\INVENTRY.BOX directory under the SMS root directory on the volume where the SMS logon server components are installed. Note that OS/2 and Macintosh clients write *.MIF files instead of *.RAW files. *.MIF files are written to the LOGON.SRV\ISVMIF.BOX directory of an SMS logon server.

At the site server, the Maintenance Manager monitors the LOGON.SRV \INVENTRY.BOX directories of the SMS_SHR share on all SMS logon servers in the site. The Maintenance Manager collects the client inventory files (*.RAW files) from these directories on the SMS logon servers, and places them in the SITE.SRV\INVENTRY.BOX directory on the site server. Inventory history files are maintained in the SITE.SRV\INVENTRY.BOX\HISTORY directory. If NetWare servers are present, the Maintenance Manager polls the INVENTRY.BOX directory on these servers for inventory information.

The Inventory Processor processes the client inventory files (*.RAW and *.MIF) and places the processed binary MIF files (*.MIF) in the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory on the site server. If the Inventory Processor cannot process a .RAW file, it places the file in the SITE.SRV\INVENTRY.BOX\BADRAWS directory. If the Inventory Processor cannot process a .MIF file, it places the file in the SITE.SRV\INVENTRY.BOX \BADMIFS directory. For more information about how the Inventory Processor processes the .RAW and .MIF files, see "How Inventory History Is Maintained" later in this chapter.

The Inventory Data Loader is a multi-threaded process (new for SMS 1.2). The main thread of the Inventory Data Loader takes the Binary MIF files in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory and places them into the PROCESS subdirectory. If the Inventory Data Loader does not have an active thread for processing .MIF inventory MIF files, it will spawn a .MIF processing thread. Note that the Inventory Data Loader can have a separate thread to process the five types of MIF files, which are distinguished by their file extensions. Also note that main thread limits the number of MIF files of each type to 1000 files of each type—when the count falls below 1000 for a type of MIF file, the main thread moves more MIF files of that type into the PROCESS subdirectory (if they exist). The thread terminates when there are no more .MIF files to process.

The .MIF processing thread renames the .MIF file before it attempts to process it; it adds an X to the beginning of the filename (for example, it would rename 12345678.MIF to X12345678.MIF). If the thread successfully processes the .MIF file, then it updates the database with the information in the file. If the MIF file is not valid, or if the thread cannot process the file for any reason, then the thread places the .MIF file in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL \BADMIFS directory. If the Inventory Data Loader terminates while processing the .MIF file, the X remains at the beginning of the filename. The thread will try to process the MIF file three times, each time adding another X to the beginning of the filename. If the thread cannot process the .MIF file successfully after three attempts, then it moves the file to the BADMIFs directory.

The .MIF processing thread updates the site database with inventory reported by the clients. After the thread has updated the site database, it moves the .MIF file to SITE.SRV\SITEREP.BOX directory to be forwarded to its parent site—if the current site has a parent site.

After the site database update, you can view the updates to the computer inventory using the SMS Administrator.

The SMS Administrator does not automatically refresh the Sites window with changes to the database (such as the addition of clients or changes to the inventories of existing clients). You may need to refresh the display for the Sites window to see new clients or changes to existing clients.

Collecting Inventory at a Secondary Site

At secondary sites, SMS collects inventory at SMS computers and collects all MIF files on the site server exactly as described in "Collecting Inventory at a Primary Site" earlier in this chapter. However, a secondary site stores all of its inventory in its parent site's database. There is no Inventory Data Loader at a secondary site to directly add the inventory information to a site database. Instead, a secondary site forwards its inventory MIF files to its parent so that the inventory information can be processed and added to the parent site's database by the Inventory Data Loader at the parent site. This process is summarized in Figure 3.6, Collecting Inventory at a Secondary Site.

Instead of writing Binary MIF files to the SITE.SRV\DATALOAD.BOX \DELTAMIF.COL directory, the Inventory Processor at a secondary site writes Binary MIF files to the SITE.SRV\SITEREP.BOX directory. The Site Reporter monitors the SITE.SRV\SITEREP.BOX directory for Binary MIF files. After it detects a queue of Binary MIF files, it creates a system job (*.JOB files in the SITE.SRV\SCHEDULE.BOX directory) to send the inventory information to the parent site. The system job file contains instructions for sending the Binary MIF files up to the parent site. The Site Reporter moves all inventory files to a subdirectory (SITECODE*) of the SITE.SRV\SITEREP.BOX directory.

The Scheduler starts the system job by compressing the Binary MIF files into a single file, jobid.P* (where jobid is the eight character job ID for the job). The jobid.P* file is placed in the SITE.SRV\SENDER.BOX\TOSEND directory in the SMS root directory.

The Scheduler also creates a despooler instruction file (jobid.I* where jobid is the eight character job ID for the job). The despooler instruction file contains instructions that the parent site uses to decompress the jobid.P* file and to process the Binary MIF files. The jobid.I* file is also placed in the SITE.SRV \SENDER.BOX\TOSEND directory.

The Scheduler then creates a send request file. A send request file (*.SRQ) contains instructions for sending the compressed package and the despooler instruction file to the parent site. Initially, the *.SRQ file is placed in the appropriate outbox directory (SITE.SRV\SENDER.BOX\REQUESTS\sender.000, where sender is the specific sender's outbox directory name, such as LAN_DEFA.000, SNA_BATC.000, or RAS_ISDN.000) for the type of sender being used to send the Binary MIF files to the parent site. For example, if a package is sent to the parent site using the LAN Sender, the SRQ file would be placed in the LAN_DEFA.000 outbox directory. You can check these directories to verify that the Scheduler has processed the job properly.

Figure 3.6 Collecting Inventory at a Secondary Site

The sender monitors its outbox for a valid send request. When it detects a send request, the sender renames it to *.SRS to indicate the send is in progress.

The sender connects to the target site and transfers the compressed package file and the despooler instruction file from the site server's TOSEND directory to the parent site's SITE.SRV\DESPOOLR.BOX\RECEIVE directory. The Despooler renames the compressed package to *.PCK. You can monitor this directory at the site server for the parent site to check the progress of the sender.

After the *.PCK file reaches its full size at the parent site, the sender transfers the instruction file as a .TMP file. When the instruction file transfer is complete, it is renamed as a valid instruction file (*.INS). This indicates that the sender has successfully processed the send request and sent the compressed file and its despooler instruction file.

At the target site server for the target site, the Despooler monitors the SITE.SRV\DESPOOLR.BOX\RECEIVE directory for despooler instruction files and processes them. The Despooler decompresses the inventory files and places them in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. The Inventory Data Loader processes the Binary MIF files and updates the site database. For more detailed information about how the Inventory Data Loader processes Binary MIF files at a primary site, see "Collecting Inventory at a Primary Site" earlier in this chapter.

How Inventory Is Reported to a Parent Site

Any site that has a parent site above it in the site hierarchy reports its inventory to its parent site. If a primary site has a site above it in the site hierarchy, it updates its own database with the client inventory (reported as Binary MIF files) of its site and child sites. Then the site forwards the client inventory up to its parent site. The client inventory is processed and forwarded until it reaches the central site.

When a child site first attaches to a parent site, the Hierarchy Manager instructs the Inventory Data Loader to create a *.INV directory (usually, this is 00000000.INV but the eight character name is a unique name assigned by the Inventory Data Loader) in the SITE.SRV\SCHEDULE.BOX directory on the site server for the child site. The Inventory Data Loader stops processing inventory MIF files at the site (files with a *.MIF) and creates a snapshot image of the computer inventory in the site database. The inventory information is extracted as a series of files, which are placed in the *.INV directory. When all the computer inventory data is extracted, the Inventory Data Loader creates a system job to send the files in the *.INV directory to the parent site and resumes processing *.MIF files at the current site.

The Scheduler processes the system job and the files in the *.INV directory are sent up to the parent site by the sender. At the parent site, the Despooler creates a *.UPD directory (usually, this is 00000000.UPD but the eight character name is a unique name assigned by the Despooler) in the parent site's SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory. The parent site's Inventory Data Loader monitors the DELTAMIF.COL directory for a directory with the *.UPD name. When it detects a *.UPD directory, it stops processing *.MIF files at the site and begins processing the files in the *.UPD directory and adds the computers from the child site to the site database. When all the computer inventory data from the child site is added, the Inventory Data Loader renames the *.UPD directory to INV*.JOB and creates a system job to send the files in the INV*.JOB directory to the parent site and resumes processing *.MIF files at the current site. This process is repeated at this site's parent site, and so on up the site hierarchy—all the way up to the central site.


How SMS Collects Inventory from Computers

The following sections describe how SMS collects inventory from clients running Windows NT, Macintosh, and OS/2.

Collecting Inventory from Clients Running Windows NT

On SMS computers running Windows NT Workstation and Windows NT Server (with the role of standalone server within a domain), the Inventory Agent is installed as a service. This service is installed and works differently than the SMS_INVENTORY_AGENT_NT service that runs on SMS logon servers running Windows NT Server. These services run at the same interval and scan for information in the same way. However, the Inventory Agent service on computers running Windows NT Workstation runs in the context of the Local System account (not the SMS Service Account as with SMS logon servers), which provides the service full access to the client. This means that the Inventory Agent service does not have direct access to network resources because the Local System account does not have access to the network.

On computers running Windows NT Workstation, the Client Monitor program complements the Inventory Agent service by providing network access to the SMS logon server. The Inventory Agent service requires network access so that updates to the package rule files (as well as the hardware and software scan intervals) can be retrieved from the SMS logon server and RAW files containing inventory reports can be copied to the SMS logon server. After the Client Monitor has copied the files, the Inventory Agent service can then use the local files to get the inventory scanning information (instead of having to connect to the SMS logon server). The Inventory Agent service writes the .RAW file (which contains the inventory report for the client) to the MS\SMS\INVDATA directory on the client. The Client Monitor then moves the .RAW files from MS\SMS\INVDATA to the SMS logon server.

The Client Monitor has three threads. The main thread manages the Client Monitor program itself; the client service thread handles special requests for restarts by the Client Configuration Manager; and the inventory helper thread provides communication between the Inventory Agent and the SMS logon server.

From the SMS logon server, the Client Monitor inventory helper thread copies the following files to the MS\SMS\DATA directory on the client:

  • DOMAIN.INI, which contains the scan intervals.
  • PKG_16.CFG, which contains the list of package rules.
  • sms_id.CFG (where sms_id is the SMS ID of the client), which is a file containing a resync command for the client.

To the SMS logon server, the Client Monitor inventory helper thread copies .RAW files from the MS\SMS\INVDATA directory on the client to the LOGON.SRV\INVENTRY.BOX directory.

When the Client Monitor starts, the inventory helper thread does the following:

  • Checks the MS\SMS\INVDATA directory on the client for any .RAW files to be moved to the SMS logon server
  • Checks the LOGON.SRV directory on the SMS logon server for any configuration files to be copied to the client. If there is a difference in date, time, or file size between the files (DOMAIN.INI, PKG_16.CFG, and sms_id.CFG) on the server and client, it copies the files from the server.

When the inventory helper thread copies .RAW files to the SMS logon server, it copies them as *.TMP to ensure that the Inventory Processor does not begin processing a file that is still being copied to the SMS logon server. After a .RAW file is copied as .TMP file, it renames *.TMP to a *.RAW file (with a unique file name) and deletes the *.RAW file on the client.

After this initial processing, the inventory helper thread sleeps and waits on the following events:

  • Directory change notification on the MS\SMS\INVDATA directory. If a new *.RAW file is added to this directory, the inventory helper thread moves it to the SMS logon server.
  • The time when the inventory configuration update interval has elapsed. The inventory helper thread checks the SMS logon server for any change in the three inventory configuration files at an interval that is one-third the Client Inventory service wake up interval. By default, the wake up interval is 24 hours; therefore, the update interval for Client Monitor is every 8 hours.

If the Inventory Agent service is not installed, the inventory helper thread spends most of its time sleeping, waiting for the client inventory installation state to change (this is set in the registry by SMS Client Setup). In this case, the inventory helper thread does not copy inventory configuration files from the SMS logon server. It will check once for any .RAW files and copy them to the SMS logon server. Thereafter, it will ignore changes to the MS\SMS\INVDATA directory—until the Inventory Agent service is installed.

Collecting Inventory from Macintosh Computers

To initiate inventory collection for the first time, a user at a Macintosh client must connect manually to an SMS logon server running Windows NT Server and Services for Macintosh, and run the Installer program. After that, inventory collection is automatic.

The user runs the Installer by selecting the Chooser to connect to the SMS logon server, and locating the MAC.BIN folder. When the user opens the Installer within the Macintosh folder, SMS files, including the INVMac program, are copied to the client. INVMac is copied to System Folder:Startup Items. When the Installer is completed, it requires that the Macintosh be restarted. At restart, INVMac runs automatically because it is a startup item.

When INVMac runs, it creates a local SMS.INI file as well as two files that store hardware and software inventory history: InvHWScanResult and InvSWScanResult. INVMac also launches the Package Command Manager (PCMMac).

INVMac puts inventory results in the LOGON.SRV\ISVMIF.BOX directory on the SMS logon server as a *.MIF file. The Maintenance Manager moves the MIF files from the Services for Macintosh logon server to the SITE.SRV \ISVMIF.BOX directory on the site server. The Inventory Processor processes these files and places them in the SITE.SRV\DATALOAD.BOX \DELTAMIF.COL directory.

At a primary site, the Inventory Processor processes these files into Binary MIF files and places them in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. The Inventory Data Loader uses the Binary MIF files to update the computer inventory in the site database and places the MIF files in the SITE.SRV\SITEREP.BOX directory for the Site Reporter to forward the MIF files to the site's parent site. For more detailed information about how inventory is processed at a primary site, see "Collecting Inventory at a Primary Site" earlier in this chapter.

At a secondary site, the Inventory Processor processes these files into Binary MIF files and places them in the SITE.SRV\SITEREP.BOX directory for the Site Reporter to forward the MIF files to the site's parent site. For more detailed information about how inventory is processed at a secondary site, see "Collecting Inventory at a Secondary Site" earlier in this chapter.

Collected files are placed in the *.CFD directory on the Services for Macintosh logon server. If there are no collected files, this directory does not exist. Files in this directory include *.FIL which are collected from the Macintosh client and one cataloging file, COLLFILE.LST. The COLLFILE.LST file is an ASCII file relating the files 0000000x.FIL to the path on the Macintosh client.

Collecting Inventory from OS/2 Computers

When the Inventory Agent for OS/2 runs on servers running LAN Manager version 2.x and LAN Server and the Inventory Agent program runs on OS/2 clients, it scans for hardware and software inventory. However, the Inventory Agent for OS/2 does not report inventory as a RAW file in the LOGON.SRV \INVENTRY.BOX directory. Instead, it creates a text MIF file and places it in the LOGON.SRV\ISVMIF.BOX directory on the SMS logon server. The Maintenance Manager moves the MIF files from the SMS logon server to the SITE.SRV\ISVMIF.BOX directory on the site server.

At a primary site, the Inventory Processor converts these files into Binary MIF files and places them in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. The Inventory Data Loader uses the Binary MIF files to update the computer inventory in the site database and places the MIF files in the SITE.SRV\SITEREP.BOX directory for the Site Reporter to forward the MIF files to the site's parent site. For more detailed information about how inventory is processed at a primary site, see "Collecting Inventory at a Primary Site" earlier in this chapter.

At a secondary site, the Inventory Processor converts these files into Binary MIF files and places them in the SITE.SRV\SITEREP.BOX directory for the Site Reporter to forward the MIF files to the site's parent site. For more detailed information about how inventory is processed at a secondary site, see "Collecting Inventory at a Secondary Site" earlier in this chapter.


How Custom Inventory Files Are Processed

SMS enables users to customize the SMS inventory by creating MIF files. MIF files are ASCII text files that contain information about a computer component, such as a hard drive or network card. You add the inventory information in a MIF file to the SMS inventory by placing it in one of the special directories dedicated for custom MIF files. SMS components periodically scan these directories and process the MIF files contained in them.

There are two types of MIF files for reporting customized client and server inventory: IDMIFs and NOIDMIFs.

IDMIFs are used for adding custom architectures and objects to the inventory. They contain Identification and Architecture groups.

NOIDMIFs are generally used for adding new groups to the inventory of a computer already existing in the database. These contain no Identification or Architecture groups.

For extensive information on customizing your inventory using MIF files, see the Microsoft BackOffice Software Development Kit.

Collecting IDMIFs

After you create an IDMIF, there are two locations that you can place the MIF file in order to add its inventory information to the SMS inventory:

  • Place the IDMIF MIF file in the LOGON.SRV\ISVMIF.BOX directory on an SMS logon server.
  • Place the IDMIF MIF file in the IDMIFs directory on an SMS client. The IDMIFs directory is specified by the StandaloneISVMIFPath entry in the [SMS] section of SMS.INI. Usually, this directory is MS\SMS\IDMIFS.

If the Inventory Agent detects an IDMIF in the MS\SMS\IDMIFS directory on a computer running Windows NT or MS-DOS, it appends the *.MIF file to the *.RAW file it created as part of regular inventory collection. The Inventory Processor then extracts the *.MIF information from the *.RAW file and uses it to create Binary MIF files in the SITE.SRV\DATALOAD.BOX \DELTAMIF.COL directory.

If the Inventory Agent detects an IDMIF on an OS/2 or Macintosh client (IDMIFs will be in the MS\SMS\IDMIFS on an OS/2 client, and in an SMS\IDMIF directory created by the user on a Macintosh client), it moves the file to the ISVMIF directory on the appropriate SMS logon server. The Maintenance Manager moves client (and server) *.MIF files found in this directory to the SITE.SRV\ISVMIF.BOX directory on the site server where they are processed by the Inventory Processor and written to the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory as Binary MIF files. (Note that the Inventory Agent programs for OS/2 and Macintosh computers write *.MIF files to the LOGON.SRV\ISVMIF.BOX directory as part of the standard inventory process.)

For more detailed information about how inventory is processed at a primary site, see "Collecting Inventory at a Primary Site" earlier in this chapter. For more detailed information about how inventory is processed at a secondary site, see "Collecting Inventory at a Secondary Site" earlier in this chapter.

Collecting NOIDMIFs

After you create a NOIDMIF, you place the MIF file on an SMS client in order to add its inventory information to the SMS inventory.

NOIDMIFs are placed in the MS\SMS\NOIDMIFS directory on SMS clients. For example, when a user at a client enters a form by using the MIF Entry tool, a *.MIF file is put in the directory that is specified by the MachineISVMIFPath entry in the client's SMS.INI file. By default, MachineISVMIFPath is the MS\SMS\NOIDMIFS directory. The next time the Inventory Agent scans for software on client's running Windows NT, Windows 3.1, Windows for Workgroups, Windows 95, or MS-DOS, it appends the information to the inventory *.RAW file. If the client is an OS/2 or Macintosh client, the Inventory Agent copies the MIF file to the client's SMS logon server (in LOGON.SRV\ISVMIF.BOX). The groups defined by the MIF files are then added to the database.

NOIDMIFs can exist only on clients, except in one case: a user can place a NOIDMIF with a *.NIM extension in the ISVMIF.BOX directory on a NetWare logon server in order to extend inventory for that server. The Maintenance Manager processes the file, which includes appending the NetWare server's architecture and identification group to it, and writes it to the DELTAMIF.COL directory as a Binary MIF file.

The Inventory Processor creates inventory history files for IDMIFs and NOIDMIFs and places them in the SITE.SRV\INVENTRY.BOX\HISTORY directory. Note that history is not created if a user copies an IDMIF with an *.NHM extension to the LOGON.SRV\ISVMIF.BOX directory. Additionally, *.NIM files do not have history.

For more information about how inventory history is maintained, see the following section.


How Inventory History Is Maintained

For each SMS computer, the Inventory Processor maintains a history file that contains the current inventory for that computer. These history files are placed in the SITE.SRV\INVENTRY.BOX\HISTORY directory on the site server.

Note

For computers running Windows NT, Windows 3.1, and MS-DOS, the Inventory Processor gives each history file a unique name¾usually, a file name with the computer's SMS ID and the extension .HMS. For Novell NetWare servers, Macintosh, and OS/2 computers, the HISTORY.MAP file maps each computer to its history file¾these history files usually have unique file names and the extension .SMH. The HISTORY.MAP file is divided into sections according to architecture; each computer is listed by NetcardID, SMSID, and SMSLocation.

When the Inventory Processor processes a subsequent RAW file (or MIF file) from a computer, it compares the inventory reported in the RAW file (groups are identified by their class and keyed attributes) to the inventory reported in the computer's history file. If there are changes, the Inventory Processor creates a Binary MIF file containing the groups whose inventories have changed (groups that have been added, updated, or deleted), and passes the file to the Inventory Data Loader. When the Inventory Data Loader detects a Binary MIF file, it then adds, updates, or deletes the groups specified in the Binary MIF file in the SMS database.

For example, the Operating System group has the class MICROSOFT|OPERATING_SYSTEM|1.0 and uses the Operating System Name attribute as a key. When the Inventory Processor reads a group of this class in the RAW file, it looks for a group with the same class and an identical value for the Operating System Name attribute. If it found a RAW file that contained a group with this class and an Operating System Name of MS-DOS, the Inventory Processor would search the history file for a group with the same class and an Operating System Name of MS-DOS. The Inventory Processor would then use the data for the group in the RAW file to update the computer's history file and add the update information to a Binary MIF file.

The Inventory Processor can add a PRAGMA statement to any group that it adds to the Binary MIF file. A PRAGMA statement tells the Inventory Data Loader what to do with a group:

Pragma | Meaning
SMS:Add | Adds the group to the computer's inventory in the database.
SMS:Update | Updates the group in the database with the information in the Binary MIF file.
SMS:Delete | Removes the group from the computer's inventory in the database.

For example, when the Inventory Processor detects that a group has been deleted, it reports the deletion by adding the group to the Binary MIF file, using a PRAGMA="SMS:Delete" statement. If no PRAGMA is specified, the Inventory Data Loader will determine the PRAGMA. If the group exists in the database, the Inventory Processor performs an SMS:Update; if the group doesn't exist in the database, it performs an SMS:Add.

If there is no change to the computer's inventory (that is, the inventory in the history file matches the RAW file), the Inventory Processor does not report a Binary MIF file. If a RAW file is processed later than four days after the last inventory report, and there is no change to the computer's inventory, the Inventory Processor will report a Binary MIF file to update the computer's Workstation Status group.


Resynchronizing Inventory Information

Whenever the Inventory Data Loader receives a Binary MIF file that does not correspond with information already existing in the site database, it issues a resynchronization (resync) command to update the site inventory.

Each Binary MIF file contains a series of group entries that describe some aspect of the computer they are associated with. MIF groups may contain an entry (called a pragma) that indicates the relationship of the group information to the information in the database. The pragma can be ADD, UPDATE, or DELETE (if a pragma statement is missing, it is assumed to be ADD). When a MIF file contains instructions to update or delete a group that is missing from the database, the Inventory Data Loader starts the resynchronization process. This process results in a full scan of the computer that generated the Binary MIF file.

For example, if you delete a computer from the inventory and do not change its reporting status, the Inventory Data Loader initiates a resync when it receives a MIF file for that computer. During the resync, it is likely that only the Identification group for that computer is available in the Personal Computer Properties - [computername] window. In this case, the event log contains an entry indicating that a resync is in progress.

Note that when a child site is attached to a parent site for the first time, a resync is not necessary. Instead, the Hierarchy Manager automatically sends up the inventory files when it detects attachment to the parent site.

The resynchronization process, also summarized in Figure 3.7, Resynchronizing Inventory Information, is as follows:

1. The Inventory Data Loader creates a system job that contains a command for the specific computer.

2. The job is passed to the Scheduler, which creates a resynchronization instruction and passes it to the sender to send to the target computer.

3. The target site Despooler runs the resynchronization instruction, which in turn creates a domain resynchronization instruction. (Because the Inventory Data Loader only sends a resync command for one computer at a time, only one domain is involved.)

When the Despooler runs the domain instruction, it writes a resync command to the master inventory command file (RESYNC.CFG) for the computer's domain. Any existing resync command for the computer is overwritten.

RESYNC.CFG is located in the SITE.SRV\MAINCFG.BOX\INVDOM.BOX \domain.000 directory on the site server. One copy of the file exists for each SMS domain.

The Maintenance Manager replicates RESYNC.CFG to the LOGON.SRV directory on all SMS logon servers. The Maintenance Manager also creates separate resync files for use by computers that are running Windows NT, have the Inventory Agent service installed, and do not have a role of SMS logon server. For each computer running Windows NT, the Maintenance Manager creates a resync file with only the resync command for that particular computer (in fact, the Maintenance Manager creates a file for each resync command in the RESYNC.CFG file but the individual files are only used by the specific type for each computer running Windows NT, as mentioned earlier). The Maintenance Manager places these resync files in the LOGON.SRV\INVENCFG.BOX. The files are named sms_id.CFG where sms_id is the SMS ID for the computer for which the resync command is intended.

At computers that are running Windows NT, have the Inventory Agent service installed, and do not have a role of SMS logon server, the Client Monitor service polls its current SMS logon server for the resync file for that particular computer every 8 hours. The Client Monitor compares the date/time and size of the resync file on the SMS logon server with the resync file on the local computer. If either of these attributes have changed or a resync file does not exist, the Client Monitor copies the resync file to the MS\SMS\INVDATA directory. If the user runs the SMS Client Setup program (either manually or via a logon script), SMS Client Setup will also compare the local and SMS logon server resync files and copies over the resync file if necessary. The Inventory Agent service wakes up every 24 hours to check if the hardware and software scan intervals have changed or elapsed. At this time, the Inventory Agent service also reads the resync file. If the file contains a pending resync command, it performs a full software and hardware scan.

At all other types of computers, RESYNC.CFG is read by the Inventory Agent program the next time the program runs. On the SMS client computer, the Inventory Agent runs manually via a RUNSMS batch file or automatically via a logon script. On SMS logon servers, the Inventory Agent service wakes up every 24 hours to check if the hardware and software scan intervals have changed or elapsed. The Inventory Agent reads the file and looks for the SMS ID of the local computer. On that computer, it checks the history file (CMNDHIS.*) to see if a resync command with a time later than the present resync command has already run. If not, the Inventory Agent performs a complete hardware and software inventory of the computer and sends the resulting *.RAW file (or *.MIF file for Macintosh or OS/2 computers) to its current SMS logon server.

Figure 3.7 Resynchronizing Inventory Information

The Maintenance Manager collects the *.RAW file from the SMS logon servers and places them on the site server in the same way that it collects *.RAW files from a normal inventory report. For more information about how inventory is processed, see "Collecting Inventory at a Primary Site" earlier in this chapter.

The Inventory Processor creates a Binary MIF file from the RAW file and places a pragma:resync attribute in the Binary MIF to indicate that it represents a resynchronization. Then the Inventory Data Loader updates the database (and forwards the Binary MIF file to its parent site) and the computer's full inventory appears in the Sites window.

Note that the Inventory Processor deletes a computer's history file if the RAW file indicates that a resynchronization has taken place. The Inventory Processor then creates a new history file.


How SMS Collects Files

SMS collects files that have the Collect This File option enabled in the package Inventory properties. The inventory collection process varies depending on your network operating system (Windows NT, LAN Manager, NetWare, or Macintosh). When the Inventory Agent scans for software, it also collects files specified by the inventory rules set for packages.

On servers running Windows NT Server and clients running MS-DOS, Windows version 3.1, Windows for Workgroups, Windows 95, and Windows NT Workstation, the Inventory Agent appends collected files to the *.RAW file containing the inventory information being reported.

On servers running LAN Manager and clients running OS/2 and Macintosh, the Inventory Agent creates a *.CFD directory beneath LOGON.SRV \ISVMIF.BOX. If no files are collected, this directory does not exist. The *.CFD directory's name begins with eight characters, which are the same as the MIF file reporting the computer's inventory. For example, if the computer's MIF file is 00000000.MIF, its collected file directory is 00000000.CFD. The *.CFD directory contains all collected files (which are renamed *.FIL to ensure the file name is unique to that computer). The directory also contains a COLLFILE.LST file, which is an ASCII text file containing the package number, path, and name where the file is found, and the renamed file name (*.FIL) of each collected file.

On NetWare servers, Maintenance Manager handles collected files the same way as OS/2 and Macintosh clients, except that the MIF file and the *.CFD directory are placed in the SITE.SRV\INVENTRY.BOX directory on the site server.

At the site server, the Maintenance Manager monitors the LOGON.SRV \INVENTRY.BOX and LOGON.SRV\ISVMIF.BOX directories of the SMS_SHR share on all SMS logon servers in the site. The Maintenance Manager collects the client inventory files (*.RAW and *.MIF) and collected files from the directories previously mentioned on the SMS logon servers and places them in the SITE.SRV\INVENTRY.BOX directory on the site server. Inventory history files are maintained in the SITE.SRV\INVENTRY.BOX\HISTORY directory.

The Inventory Processor processes the client inventory files (*.RAW and *.MIF), extracts the collected files from the *.RAW files, places the processed files (*.MIF) in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory on the site server, compresses the collected files (files extracted from the *.RAW files and files collected as *.FIL files), and appends these compressed files to the *.MIF files. These processed files are called inventory Binary MIF files.

The Inventory Data Loader processes Binary MIF files and updates the site database with inventory reported by the clients. It also decompresses the collected files and places them in a subdirectory beneath SITE.SRV \DATALOAD.BOX \FILES.COL. The subdirectory structure reflects the hierarchy of sites, as follows: site_code\range_of_smsids\smsid. Note that range_of_smsids is the first ID in the range. All of the collected files for the computer are placed in that computer's SMSID subdirectory. If there is a conflict in the file name, a random four-digit sequence is appended to the extension. For example, if you collected two AUTOEXEC.BAT files from a computer with SMS ID RED12345, SMS will create a subdirectory RED\RED12300\RED12345 beneath the SITE.SRV \DATALOAD.BOX\FILES.COL directory. Both collected files are stored in that subdirectory; one as AUTOEXEC.BAT, the other as AUTOEXEC.BAT_4EBD (where the digits 4EBD appended to the file extension are four digits selected randomly for this example).

The Inventory Data Loader copies all Binary MIF files that cannot be processed to a BADMIFS subdirectory. For more detailed information about how the Inventory Data Loader processes Binary MIF files at a primary site, see "Collecting Inventory at a Primary Site" earlier in this chapter.

After the site database is updated, you can view the collected files using the SMS Administrator.


How SMS Maintains Package Inventory Rules and SMS Network Application Configurations

Package and program group properties defined in a site's database are used to define software for which the Inventory Agent should scan and to configure program group offerings within the site. If a site is part of site hierarchy, the package and program group configuration information is propagated from the parent site down to the current site. Each parent site propagates its own package and program group configurations as well as those of its parent site.

For example, if site A is a parent site of site B and site B is a parent site of site C, site A propagates all its package and program group configuration information to site B; site B propagates its own package and program group configuration as well as those received from site A down to site C. Site C contains package and program group configuration information for sites A and B as well as those defined at site C.

When you create, modify, or delete a package or program item, SMS modifies the site database. A site database contains properties for all packages and program groups created at the current site and the sites above it in the hierarchy. The Applications Manager monitors the site database but it does not make changes until the packages and program group windows go through a period of inactivity. Updating the PACKAGE.RUL file is dependent on the polling intervals of both the Applications Manager and Maintenance Manager.

If a user doesn't make changes to packages and program groups for 10 minutes, the Applications Manager processes the change. This gives users time to modify packages and program groups without causing unnecessary package and program group updates.

When the Applications Manager processes a change in package properties, it updates the inventory detection rules at the current site. For more information about how inventory detection rules are updated at the current site, see "Maintaining Package Inventory Rules Within a Site" later in this chapter.

When the Applications Manager processes the change in package properties or program group properties at the current site, the Applications Manager updates the configuration files that are used by Program Group Control at Windows-based clients to set up and run SMS network applications. For more information about how network applications are configured within a site, see "SMS Network Applications" later in this chapter.

After the Applications Manager updates the local site's configuration, it creates transaction files to be sent to all its direct child sites. This process is summarized in Figure 3.8,Transaction Files.

The Applications Manager creates the following types of transaction files:

  • *.PAC (added or changed packages)
  • *.DPK (deleted packages)
  • *.GRP (added or changed program groups)
  • *.DPG (deleted program groups)

The Applications Manager then creates a job that sends all package and program group information to the sites directly beneath it in the hierarchy.

The Scheduler compresses these files into a single jobid.P* file (where jobid is the eight character job ID for the job) and creates a despooler instruction file. For each target site specified, the Scheduler also creates a send request file. A send request file (*.SRQ) contains instructions for sending the compressed package and the despooler instruction file to the target site. The sender transfers the jobid.P* file and despooler instructions to the lower-level sites.

At each site, the Despooler decompresses the files in the package and places them in the SITE.SRV\SITECFG.BOX directory on the site server. The Applications Manager at the site updates the site's database with the package and program group information in the transaction files. After Applications Manager updates the database, it also updates that site's inventory and SMS network application configuration and creates a job to send all its database's package and program group properties to its subsites. When a package gets sent to a child site that is a secondary site, Applications Manager stores the *.PAC and *.GRP files in the SITE.SRV\APPMGR.BOX directory rather than in the site database.

Maintaining Package Inventory Rules Within a Site

A package's inventory rules resides at the site where the package was originally created and are propagated to all subsites. The SMS system scans for the package on all clients at the originating site and all of its subsites. For more information about how package inventory rules are propagated to subsites, see "How SMS Maintains Package Inventory Rules and SMS Network Application Configurations" earlier in this chapter.

When you define Inventory properties for a package, SMS adds the package's inventory rules to the site's database. A site's database contains properties for all packages created at the current site and the sites above it in the hierarchy. The Applications Manager monitors the site database but it does not make changes until the packages and program group windows go through a period of inactivity. Updating the PACKAGE.RUL file is dependent on the polling intervals of both the Applications Manager and Maintenance Manager.

Figure 3.8 Transaction Files

If a user doesn't make changes to packages and program groups for 10 minutes, the Applications Manager processes the change. This gives users time to modify packages without causing unnecessary package property updates.

When the Applications Manager detects a change in a package's properties followed by a period of inactivity, it updates the site's PACKAGE.RUL file. The PACKAGE.RUL file contains rules for all packages inventoried at the site. Maintenance Manager uses the PACKAGE.RUL file to create the Inventory Agent program's configuration files, which contain rules for collecting inventory. Maintenance Manager replicates these configuration files (PKG_16.CFG) to all SMS logon servers for all SMS domains in the site. When the Inventory Agent program runs at a client in the site, it scans for packages defined in the site's database.

This process is summarized in Figure 3.9, Package Inventory Rules Update.

Figure 3.9 Package Inventory Rules Update


Software Distribution

The following sections describe how SMS processes Run Command On Workstation jobs, Share Package On Server jobs, Remove Package From Server jobs, and SMS network applications. It also describes how SMS selects default distribution servers for jobs.


Run Command On Workstation Jobs

This section describes how Run Command On Workstation jobs are transmitted from the site database to SMS logon servers and clients. This process is summarized in Figure 3.10, Run Command On Workstation Software Distribution.

A Run Command On Workstation job runs a command defined for a package at specified clients. You can use a Run Command On Workstation job to install a package or to run a command on individual clients.

To install a package on clients, you create a package with Workstations properties, and then create a Run Command On Workstation job for that package. After the job is created, it is added to the site database where the Scheduler monitors all jobs created at the site.

The Scheduler has a polling interval for checking jobs in the SMS database. This polling interval is based on the Response setting in the Services dialog box within Site Properties. This means that if the Scheduler is in the inactive state of a polling interval, it may not detect all new jobs or active jobs (or any changes to a job) at the moment that their Start After times elapse—the Scheduler will detect and process the new, active, or changed jobs when the current polling interval elapses, at which time it will check the jobs in the SMS database.

After the job's Start After time elapses, the Scheduler starts the job by creating a compressed package file (packageid.W* where packageid is the eight character package ID for the package used by the job) that contains all subdirectories and files within the package's source directory. The packageid.W* file is placed in the SITE.SRV\SENDER.BOX\TOSEND directory of the SMS root directory.

The Scheduler then creates a despooler instruction file for each target site. A despooler instruction file contains instructions for completing the job at each target site (instructionid.I* where instructionid is the five character unique ID in the job ID followed by the site code for the target site). The instructionid.I* file is placed in the SITE.SRV\SENDER.BOX\TOSEND directory.

Figure 3.10 Run Command On Workstation Software Distribution

For each target site specified for the job, the Scheduler also creates a send request file. A send request file (*.SRQ) contains instructions for sending the compressed package and the despooler instruction file to the target site. Initially, the *.SRQ file is placed in the appropriate outbox directory (SITE.SRV\SENDER.BOX \REQUESTS\sender.000 where sender.000 is the specific sender's outbox directory name, such as LAN_DEFA.000, SNA_BATC.000, or RAS_ISDN.000) for the type of sender being used to send the job to the target site. For example, if a package is sent to the target site using the LAN Sender, the SRQ file would be placed in the LAN_DEFA.000 directory of the REQUESTS directory.

You can check these directories to verify that the Scheduler has processed the job properly.

Note

If you have created a job with the current site as the target, SMS uses the same method for transmitting the package and instructions as a job targeted to child sites. When you install a primary site, a LAN Sender is automatically installed and a LAN Sender address is also automatically created for the site itself. This address is used for the sending process for jobs created at the current site and targeted at the site itself. You should never delete this address.

The sender monitors its outbox for a valid send request. When it detects a new send request, it renames it to *.SRS to indicate the send is in progress.

The sender connects to the target site and transfers the compressed package file and the despooler instruction file from the SITE.SRV\SENDER.BOX\TOSEND directory on the site server to the SITE.SRV\DESPOOLR.BOX\RECEIVE directory on the target site server. The Despooler renames the compressed package to *.PCK. This directory can be monitored at the site server to check the sender's progress.

After the *.PCK file reaches its full size at the parent site, the sender transfers the instruction file as a .TMP file. When the instruction file transfer is complete, it is renamed as a valid instruction file (*.INS). You can verify the compressed package and its instruction file were properly sent to the target site by checking the SITE.SRV\DESPOOLR.BOX\RECEIVE directory on the destination site server.

At the site server for the target site, the Despooler monitors the SITE.SRV \DESPOOLR.BOX\RECEIVE directory for instruction files and then processes the files. The Despooler moves the compressed package to the SITE.SRV \DESPOOLR.BOX\STORE directory. Packages for Run Command On Workstation jobs are saved as packageID.WKS.

Next, the Despooler at the target site decompresses the compressed package (.WKS file) into the package source directory's original files and directory structure. The Despooler decompresses the package directory into a temporary directory located at the root directory of the local drive with the most free space.

Note that if the package contains NTFS-format files (such as Macintosh files or files with a long file name or unique characters), the Despooler uses the local NTFS drive with the most free space for its temporary directory.

Note that a preferred drive can be set in the following registry key: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_DESPOOLER\Preferred Drive For Temp Directory.

The Despooler copies the decompressed package directory and files from the temporary directory to the target distribution servers specified by the job. Where the package directory is then placed on each target distribution server depends on the type of server:

  • On SMS logon servers running Windows NT Server, LAN Manager, or LAN Server, the Despooler creates a subdirectory in the SMS_PKGx share where x specifies the drive where the directory is located. The package ID is used for the name of the new subdirectory, and the package is installed in this directory.

If SMS_PKGx has not already been created, the Despooler determines the drive that contains the SMS_SHR share. If this share has at least 100 MB of free space, it is used. If there is less than 100 MB free, the Despooler uses the NTFS drive with the most available free space. If no NTFS drive has at least 100 MB free, it uses the non-NTFS drive with the most available free space. If no other drives have 100 MB free, the drive containing the SMS_SHR is used. Note that the minimum free space requirement is 100 MB by default; however, it can be set in the following registry key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_DESPOOLER\SMS Drive Minimum Free Space in Mbytes

The only exception to this is if the SMS root directory is on a drive formatted as FAT and the package requires NTFS (such as a Macintosh package or a package source directory that contains NTFS long names). In this case, the Despooler searches for a drive formatted as NTFS. If it finds an NTFS drive, the Despooler creates the SMS_PKGx directory at the root of that drive (where x is the drive letter), shares the directory as SMS_PKGx, creates a subdirectory (beneath that directory) with the same name as the package ID, and installs the package in this subdirectory. If no NTFS drive is found, the Despooler retries up to 100 times, waiting the amount of time specified by its set interval between each retry.

  • On SMS logon servers running NetWare, the Despooler installs the package on the volume where the SMS logon server components are installed. The Despooler creates a subdirectory (beneath the smsroot\logon.srv \PCMPKG.SRC directory) with a name that is the same as the package ID. The package is installed in this directory.
  • On computers running Windows NT Workstation (or servers that are running Windows NT Server, LAN Manager, or LAN Server but are not SMS logon servers), the package is installed only if the SMS Service Account is a member of the computer's Administrators group. If the computer doesn't already have an SMS_PKGx share (where x is the drive letter), the Despooler creates an SMS_PKGx directory at the root of the drive with the most free disk space. It shares the directory as SMS_PKGx, creates a subdirectory with the same name as the package ID, and installs the package in this directory.

After the Despooler copies the decompressed package from the temporary directory to all the target distribution servers, the Despooler deletes the temporary directory and its contents. The Maintenance Manager creates a Package Location MIF file (*.PMF) that is reported back to the sending site. This information is written to the database. It indicates where the package has been installed. When you do Remove Package From Server jobs, the package can only be removed from servers reported in a Package Location MIF file.

For a Run Command On Workstation job, the Despooler uses the job's despooler instruction file to create a PCM instruction file for each target client in the target site's domains. PCM instruction files contain package installation instructions for individual clients. For each domain in the site, there is a domain master box where PCM instruction files for the domain are placed. The domain master box directory is SITE.SRV\MAINCFG.BOX\PCMDOM.BOX\domain_name.000. For each target client, a PCM instruction file for the target client is placed on all SMS logon servers in the SMS domain containing that client.

You can verify the PCM instruction files (workstation_unique_ID.INS) were created by checking the SITE.SRV\MAINCFG.BOX\PCMDOM.BOX \domain_name.000 directories on the site server.

Maintenance Manager replicates the PCM instruction files from the SITE.SRV\MAINCFG.BOX\PCMDOM.BOX\domain_name.000 directories on the site server to the LOGON.SRV\PCMINS.BOX directory on all the SMS logon servers in the target domains. The PCM instruction file is named according to the client's SMS ID (for example, D9500002.INS).

At the SMS client, Package Command Manager monitors the LOGON.SRV \PCMINS.BOX directory of the client's SMS logon server for new PCM instruction files. A package appears in the Package Command Manager window when the client's time is later than the Offer After time set for the job. To run the package command, the user at the client selects the package and chooses the Run button. The Package Command Manager runs the package's command.

Note

There are four possible extensions for an instruction file (*.INS, *.SNI, *.IST, and *.NIL). There are four possible file names for a package (*.PCK, *.PKG, packageid.SRV, and packageid.WKS).

SMS components only create instructions as *.SNI or *.INS. The *.INS files contain compressed instructions and the *.SNI files hold decompressed instructions. An *.INS or *.SNI instruction becomes *.IST or *.NIL when the Despooler starts processing the instruction. A *.IST file is for instructions which have an accompanying package file. A *.NIL file is for standalone instructions.

The *.PCK files become *.PKG files the moment their respective *.INS or *.SNI files become *.IST files. When the Despooler at the receiving site moves a compressed *.PKG file into the SITE.SRV\DESPOOLR.BOX\STORE directory, it renames it to packageID.WKS (for client packages) or packageID.SRV.

Status Reporting for Run Command On Workstation Jobs

After the Package Command Manager completes a package installation (that is, it has run the package command), it creates a despooler instruction file that reports status for the Run Command On Workstation job. The Package Command Manager places the file in the DESPOOLR.BOX directory specified by the ResultsSharePoint entry in the client's SMS.INI file. If the SMS logon server is a NetWare server, the file is placed on the volume containing the SMS installation directory on the server. If the package installation script calls the ISVMIF DLL to report status or writes a text status MIF file to the Windows directory, the Package Command Manager puts this file in the DESPOOLR.BOX as a *.MIF file.

After running a package, the Package Command Manager also modifies the PCMHIST.REG file to indicate the package was run. The PCMHIST.REG file is located in the MS\SMS\DATA directory on the client. All information about whether a command has been run, has been archived, or is pending is stored in this file.

The Maintenance Manager monitors the DESPOOLR.BOX on all SMS logon servers and moves files back to the SITE.SVR\DESPOOLR.BOX\RECEIVE directory on the site server. The Despooler reads the instruction file and processes the instruction. It also updates the master copy of the PCM instruction file in the DOMAINMASTERINBOX directory (SITE.SRV\MAINCFG.BOX \PCMDOM.BOX\domain.name.000). The Maintenance Manager copies this file to the LOGON.SRV\PCMINS.BOX directory on all SMS logon servers in the SMS domain containing the client.

The Despooler then creates a job status MIF file which reports the package installation status from the client back to the site where the job was created. The job status MIF file has an extension of .JMF. This .JMF file is sent up the hierarchy just like an event MIF file, inventory MIF file, or other MIF file. Note that job status MIF files in SMS 1.0 had an extension of .MIF. For primary sites, the .JMF file is placed in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. For secondary sites, the .JMF file is placed directly in the SITE.SRV \SITEREP.BOX directory. If the package command reports a failed status, the Despooler logs an event to the Windows NT event log on the site server and writes an error event MIF file (event MIF files have an extension of .EMF) to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory on the site server. If the package command created a text status MIF file, the description attribute is included in this event. For information about how events are reported, see "Event Processing" later in this chapter.

If the current site is the originating site for the job, the Inventory Data Loader reads the .JMF file and uses it to update the job's status in the site database. The Inventory Data Loader is a multi-threaded process (new for SMS 1.2). The main thread of the Inventory Data Loader takes the MIF files in the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory and places them into the PROCESS subdirectory. If the Inventory Data Loader does not have an active thread for processing .JMF files, it will spawn a .JMF processing thread. Note that the Inventory Data Loader can have a separate thread to process the five types of MIF files, which are distinguished by their file extensions. Also note that the main thread limits the number of MIF files of each type to 1000 files—when the count falls below 1000 for a type of MIF file, the main thread moves more MIF files of that type to the PROCESS subdirectory. The .JMF processing thread updates the site database with job status reported by the clients. Note that the thread performs a syntax check on the .JMF file and places these files in the BADMIFS subdirectory if the MIF file cannot be processed. If there are no more MIF files to process, the thread terminates.

If the current site is a primary site that is not the originating site for the job, the Inventory Data Loader moves the .JMF file to the SITE.SRV\SITEREP.BOX directory. If the current site is a secondary site, the Despooler places the .JMF directly in the SITE.SRV\SITEREP.BOX directory (and never in the SITE.SRV \DATALOAD.BOX\DELTAMIF.COL directory).

When the Site Reporter detects a queue of MIF files, it creates a system job that sends the MIF files to the current site's parent site. The trigger queue length is determined by Service Response settings in the Site Properties dialog box.

The system job's instruction file is placed in the SITE.SRV\SCHEDULE.BOX directory. The Scheduler monitors this directory for system job instructions. For each system job, the Scheduler creates a despooler instruction file (jobid.I* where jobid is the eight character job ID for the job) and compresses the MIF files into a single file (jobid.P*). These files are placed in the SITE.SRV\SENDER.BOX \TOSEND directory.

The Scheduler then creates a send request file (*.SRQ) in the appropriate sender's outbox directory. The sender processes the request and transfers the data to the parent site. At the parent site, the Despooler reads the instruction file and carries out its instructions by decompressing the compressed file containing the MIF files in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory on the site server.

If the parent site is not the originating site for the job, the Inventory Data Loader moves the .JMF file to the SITE.SRV\SITEREP.BOX directory and forwards it to its parent site, and so on until it reaches the originating site.

If the parent site is the originating site for the job, the Inventory Data Loader reads the .JMF file, moves it to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL \PROCESS directory, and uses it to update the job's status in the site database.

To view job status reported by Package Command Manager, open the Job Properties dialog box for the job, choose the Status button, select the site for which you want to view status, and choose the Details button. The job's status at each client and distribution server is displayed in the list box.

How Package Command Status MIF Files Are Processed

A package command can write a MIF file to the Windows directory to provide more detailed status. This status MIF file is called a package command status MIF file. A program started by a package command can also call a function from the ISVMIF DLL to report status on the job that corresponds to the package command. For more information on reporting status with the ISVMIF DLL, see the Microsoft BackOffice Development Kit. For information about the package command status MIF file format, see Chapter 4, "File Formats."

If a program writes a MIF file to the Windows directory, Package Command Manager collects the file and places it (and the despooler instruction file) in the DESPOOLR.BOX directory specified by the ResultsSharePoint entry in the client's SMS.INI file. Note that the date and time on the MIF file must be later than the date and time specified for the job start time (or Package Command Manager will not collect the file).

The package command status MIF file has priority over the despooler instruction file. This means that the Despooler uses the status reported in the package command status MIF file to create a job status MIF file (*.JMF). The job status MIF file reports the job status up the hierarchy to the site where the job was created. If a failure occurs, the job status MIF file includes a text description of the failure reported by the package command status MIF file, and the Despooler logs an event in the Windows NT event log on the site server using this description.

A package command status MIF file includes one group (InstallStatus) that contains two attributes (Status and Description).

The Status attribute determines the status reported back to the originating site. This status is included in the job details status MIF file that the Despooler writes and that eventually makes its way back to the originating site's job details data for this job in the database.

The Description attribute is used only if the Status is FAILED—in which case, the Description is used as text in an SMS event and a Windows NT event. If the MIF file contains a FAILED status and includes a description string, the string is reported by the Despooler in a Windows NT event to the computer's site server Windows NT event log and is reported as an SMS event, which also eventually makes its way back up the site hierarchy to the originating site's database. If the MIF file contains a SUCCESS status, the description string is not reported back.

In the SMS Administrator, you can view the status in the Job Status Details dialog box for the job. If the package command reports a FAILED status, you can view the generated event in the Events window in the SMS Administrator.


Share Package On Server Jobs

This section describes how Share Package On Server jobs are transmitted from the originating site to the target site and distribution servers. This process is summarized in Figure 3.11, Share Package On Server Software Distribution.

Figure 3.11 Share Package On Server Software Distribution

A Share Package On Server job installs a package on servers, shares the directory containing the package and all its files, and makes them available to users according to the access permissions specified by the job.

To share a package on servers, you create a package with Sharing properties, and then create a Share Package On Server job for that package. After the job is created, it is added to the site database where the Scheduler monitors all jobs created at the site.

The Scheduler and sender process is exactly the same as the process for Run Command On Workstation jobs—except that the Scheduler creates a compressed package with the name packageid.S* (whereas a Run Command On Workstation job uses the name packageid.W*). The process for Run Command On Workstations jobs is described in "Run Command On Workstation Jobs" earlier in this chapter.

At the site server for the target site, the Despooler monitors the SITE.SRV \DESPOOLR.BOX\RECEIVE directory for instruction files and then processes the files. The Despooler moves the compressed package to the SITE.SRV \DESPOOLR.BOX\STORE directory. Packages for Share Package On Server jobs are saved as packageID.SRV.

Next, the Despooler at the target site decompresses the compressed package (.SRV file) into the package source directory's original files and directory structure. The Despooler decompresses the package directory into a temporary directory located at the root directory of the local drive with the most free space. The selection and usage of the temporary directory is exactly the same as the process for Run Command On Workstation jobs.

The Despooler copies the decompressed package directory and files from the temporary directory to the target distribution servers specified by the job. Where the package directory is then placed on each target distribution server depends on the type of server:

  • On SMS logon servers running LAN Manager or Windows NT Server, the Despooler creates a directory (with the same name as the share name specified for the package) at the root of the drive with the most free space. The Despooler shares that directory using the specified share name and installs the package in that directory. If the package share name already exists, the Despooler copies the package to the existing share.
  • On SMS logon servers running NetWare, the Despooler tries to install the package to the volume specified for the package. Within the Sharing properties of the package, you should specify a volume name and a subdirectory for share name (for example, myvol\mydir).

If you specify TEST\ONE as the share name, and TEST is an existing volume, the Despooler puts the package in \\servername\TEST\ONE. If TEST is not a volume name on the NetWare server, the Despooler puts the package in \\servername\defaultvolume\TEST\ONE.

The default volume is the volume where SMS is installed; if SMS is not installed on the NetWare server, the Despooler creates the package share on the SYS volume.

If you specify only TEST as the share name, and TEST is an existing volume on the NetWare server, the Despooler puts the package in \\servername\TEST \packageID. If TEST is not a volume name on the NetWare server, the Despooler puts the package in \\servername\defaultvolume\TEST.

Thus, if you specify TEST\ONE as your volume and share name, all NetWare distribution servers should have a volume called TEST with enough space to install the shared package directory. If you specify a share name that does not exist on NetWare servers, the default volume on each server must have enough room for the package. If adequate space is not available on the default volume, the shared package directory is not created and an event is written to the SMS event log.

  • On computers running Windows NT Workstation, the package is installed only if the SMS Service Account is a member of the computer's Administrators group. The Despooler creates a directory (with the same name as the share name specified for the package) at the root of the drive with the most disk space. The Despooler shares this directory using the specified share name and installs the package in that directory.


Remove Package From Server Jobs

When a Remove Package From Server job is created, the Despooler removes all files from all or some target site distribution servers, depending on which job task is specified (Remove From All Distribution Servers or Remove From Selected Distribution Servers). SMS uses the Package Location data in the database to determine which servers have a copy of the package.

This process is summarized in Figure 3.12, Remove Package From Server Job Flow.

Error! Not a valid filename.

Figure 3.12 Remove Package From Server Job Flow

For the Remove From All Distribution Servers option, the Despooler:

  • Removes the compressed version of the package from the target site servers.
  • Removes the decompressed versions of the package from all distribution servers.
  • Removes the commands from PCM instruction files for all target SMS computers for all jobs that use the removed package. Note that this is the only way to remove commands from PCM instruction files (except by using the SMS Administrator to cancel each job that uses the package).
  • Leaves packages that have been installed on clients.
  • Leaves the package source directory at the originating site.
  • Leaves the compressed version of the package at the originating site. This is the compressed package created by the Scheduler in the SITE.SRV\SENDER.BOX\TOSEND directory on the originating site server. There are two ways to remove this compressed package: 1) Delete the package from the Packages window in the SMS Administrator. 2) Manually delete the compressed file (you can identify it by its file name: packageid.W* for a workstation package and packageid.S* for a server package).

For the Remove From Selected Distribution Servers option, the Despooler:

  • Removes the decompressed versions of the package from all distribution servers in the specified machine group.
  • Leaves packages that have been installed on clients.
  • Leaves the package source directory at the originating site.
  • Leaves the compressed version of the package at the originating site. This is the compressed package created by the Scheduler in the SITE.SRV\SENDER.BOX\TOSEND directory on the originating site server. There are two ways to remove this compressed package: 1) Delete the package from the Packages window in the SMS Administrator. 2) Manually delete the compressed file (you can identify it by its file name: packageid.W* for a workstation package and packageid.S* for a server package).

A Remove Package From Server job applies to both Run Command On Workstation and Share Package On Server jobs. After a Remove Package From Server job's Start After time elapses, SMS sends the job's instructions to designated sites. Using the job instructions, the Despooler removes the decompressed version of the package from the specified distribution servers. If you selected the Remove From All Distribution Servers option, the Despooler also removes the compressed version of the package from the site server's DESPOOLR.BOX\RECEIVE\STORE directory.

Note that if you limit package removal to sites A and B, and then specify a machine group containing a distribution server that is part of Site C, no files are removed from the server that is part of site C.


SMS Network Applications

This section discusses how configuration information for setting up and running SMS network applications is transmitted from the site database to SMS logon servers and clients. This process is summarized in Figure 3.13, SMS Network Application Software Distribution.

Figure 3.13 SMS Network Application Software Distribution

When you set up an SMS network application within SMS, you create program items within packages, create program groups that contain the program items you want to offer, and assign program groups to the user groups to which you want to offer program items. There are two SMS programs that configure and run the SMS network applications on clients: the Application Control program, and the Application Start program. Together, these programs are often referred to as the Program Group Control application. These programs are described later in this section.

Package and program group properties defined in a site's database are used to configure program group offerings within the site. If a site is part of site hierarchy, the package and program group configuration information is propagated from the parent site down to the current site. Each parent site propagates its own package and program group configurations as well as those of its parent site.

For example, if site A is a parent site of site B and site B is a parent site of site C, site A propagates all its package and program group configuration information to site B; site B propagates its own package and program group configuration as well as those received from site A down to site C. Site C contains package and program group configuration information for sites A and B as well as those defined at site C. For more information about how package configurations and program group configurations are propagated from the parent site to its child sites, see "How SMS Maintains Package Inventory Rules and SMS Network Application Configurations" earlier in this chapter.

As noted earlier, all configuration information needed to set up and run SMS network applications at the site is stored in the site database. From the configuration information in the site database, the Applications Manager creates configuration files that are used by Program Group Control at Windows-based clients to set up and run SMS network applications. The Applications Manager creates and maintains two sets of configuration files: one for program items (*.HAF) and one for program groups (*.HGF). These files are located in the SITE.SRV\MAINCFG.BOX\APPCTL.SRC\DATABASE directory. These files serve as a database that Program Group Control can query to find out which program groups are assigned to the current user at the client and to retrieve configuration information for the program groups and their program items.

The Maintenance Manager replicates the .HAF and .HGF files to the SMS logon servers for all SMS domains in the current site. On the SMS logon servers, .HAF and .HGF files are located in the LOGON.SRV\APPCTL.BOX\DATABASE directory.

The Application Control program reads the Program Group Control files and creates the program groups for the appropriate SMS network applications. The Application Control program runs only on Windows-based clients at the site. There are three versions of the Application Control program: APPCTL95 for Windows 95 clients, APPCTL32 for Windows NT clients, and APPCTL16 for 16-bit Windows clients.

When a user logs on to the network, the Application Control program retrieves the list of user groups of which the current user is a member. How this list is retrieved depends on the type of client:

  • For clients running the Windows NT operating system, the Application Control program retrieves the list of user groups from the SMS domain containing the servers listed in the [Servers] section of SMS.INI.
  • For clients running the LAN Manager network operating system, the Application Control program retrieves the list of user groups from the SMS domain containing the server specified by the ValidatingServer entry in the [SMSLSIni] section of SMS.INI. If no server is specified in this entry or if it is unavailable, the Application Control program searches for a network logon server in the domain where the client has been logged on and retrieves the list of user groups from that server.
  • For clients running the NetWare network operating system, the Application Control program retrieves the list of user groups from all SMS logon servers listed in the [Servers] section of SMS.INI.

Next, the Application Control program connects to the server specified by CurrentLogonServer entry in the [Servers] section of the client's SMS.INI file. If this server is not available, it uses an algorithm to randomly select an SMS logon server from the other servers listed in the [Servers] section of SMS.INI.

Based on the user group memberships for the user, the Application Control program retrieves the list of assigned program groups and the configurations for the program items in those program groups. It then creates the assigned program groups in the client's Program Manager. It also creates entries in the client's registry to configure the program items for all assigned program groups.

Note that on clients running Windows 95 and Windows NT version 4, the Application Control program adds the groups as menu items under Programs in the Start menu.

When the Application Control program creates the program items for an SMS network application, it configures the program item command line to call the Application Start program. When the user selects the program item, the Application Start program actually installs, configures, and runs the SMS network application. There are three versions of the Application Start program: APPSTA95 for Windows 95 clients, APPSTA32 for Windows NT-based clients, and APPSTA16 for 16-bit Windows-based clients.

If either the Application Control program or the Application Start program encounters any errors, it logs the errors to a local log file called PGC.LOG.This log file is located in the MS\SMS\LOGS directory on the client. Some errors are reported to the SMS logon server as SMS event MIF files, which are eventually added to the site database so that you can view these errors in the SMS Events window in the SMS Administrator.


How Default Distribution Servers Are Selected

When the Scheduler activates either a Run Command On Workstation job or a Share Package On Server job, it builds the list of target distribution servers from the machine group you specified in the Put On Specified Distribution Servers box in the Job Details dialog box. The distribution server list is compiled at the time that the Scheduler activates the job, so if you added a computer to a machine group between the time the job was created and when it was activated, this new computer is included in the distribution server list. If you added a computer after the job is activated, the new computer is not included.

The Scheduler puts all the computers from this machine group into the distribution server list, regardless of what types of computer they are.

When the Despooler processes the job, it tries to install the package on the target servers.

If a target site for the job does not have a computer in the specified machine group, the Scheduler uses the servers listed in that target site's Default Servers group.

If you select the Default Servers machine group as the distribution target, the Scheduler creates the list of target distribution servers from the Default Servers set for each target site. When the Scheduler activates the job, the Scheduler uses the Default Servers currently stored in the site database for the target sites.

Note that the Default Servers group can contain computers that are not part of the SMS system. If you use a non-SMS computer, you must ensure that the SMS Service Account has administrative privilege for the computer. The Despooler treats a non-SMS computer like a computer running Windows NT Workstation.

Note that the Despooler retries failed instructions (including the instruction to place a package on a distribution server) 100 times at the retry interval before it stops processing the instruction and reports that the instruction could not be completed. The retry interval is set according to the site's service response rate.


Event Processing

SMS can have its system components installed on different computers in a site. For example, an SNA Sender can be installed on another server (that is, a server other than the site server).

When an SMS component reports an event to the SMS system, it first logs an event in the Windows NT event log of the computer where the component is running. The component then reports the event in two steps to the site server for the site:

1. At a primary site, the component writes an event MIF file (*.EMF) to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory of the SMS root directory on the site server. The Inventory Data Loader service updates the site database if the site is a primary site, and forwards the .EMF file to the site's parent site.

At a secondary site, the component writes an .EMF file to the SITE.SRV\SITEREP.BOX directory on the site server. The Site Reporter creates a system job to send the .EMF file up to the site's parent site.

2. The component logs an event to the Windows NT event log on the site server.

This process is summarized in Figure 3.14, Figure 3.15, and Figure 3.16.

Figure 3.14 How events are reported in a site.

When the .EMF file is forwarded to the site's parent site, the Inventory Data Loader updates that site's database and forwards the event MIF file to its parent site. By processing and forwarding .EMF files, the system reports events up the site hierarchy—all the way up to the central site.

Using the Events window of the SMS Administrator, you can view events for the site where you are logged in and all sites beneath that site.

Note

If a component cannot create or write the .EMF file (for example, if the site server is out of disk space), the event may not be reported to the site database. In this case, the Windows NT event log of the computer where the event occurred may contain the only record of the event.

Figure 3.15 How events are reported by a service installed on another server (that is, a service not installed on the site server).

Figure 3.16 How events are forwarded up the site hierarchy.

The SMS Executive, Site Configuration Manager, and Hierarchy Manager services maintain event history on some of their events. When an event that uses event history occurs, the SMS service or component reads its event history file from the ERRORHIS subdirectory beneath the directory where the service or component is installed. The SMS Executive (SMS_EXEC.HIS), the Site Configuration Manager (SMS_SITE.HIS), and Hierarchy Manager (SMS_HIER.HIS) have their own history files. The component or service checks its event history file for a record of the condition that generated the event. If the condition is the same as the last recorded event, no event is reported. If the condition has changed, the event is reported with the updated status. If the status is a success or recovery report, the component clears the event record from its error history file.

How the Inventory Data Loader Processes .EMF Files

The Inventory Data Loader is a multi-threaded process (new for SMS 1.2). The main thread of the Inventory Data Loader takes the Binary MIF files in the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory and places them into the PROCESS subdirectory. If the Inventory Data Loader does not have an active thread for processing .EMF event MIF files, it will spawn a .EMF processing thread. Note that the Inventory Data Loader can have a separate thread to process the five types of MIF files, which are distinguished by their file extensions. Also note that main thread limits the number of MIF files of each type to 1000 files—when the count falls below 1000 for a type of MIF file, the main thread moves more MIF files of that type into the PROCESS subdirectory.

The .EMF processing thread updates the site database with events reported by SMS components. After the thread has updated the site database, it moves the .EMF file to SITE.SRV\SITEREP.BOX directory to forward the .EMF to its parent site—if the current site has a parent site. Note that the thread performs a syntax check on the MIF file and does not copy to the SITE.SRV\SITEREP.BOX if the MIF file cannot be processed; these unprocessable MIF files are placed in theBADMIFS subdirectory. If there are no more .EMF files to process, the thread terminates.


Remote Troubleshooting

SMS supports remote troubleshooting for clients running MS-DOS, Windows, Windows for Workgroups, Windows 95, and Windows NT. This section contains information about the system flow of remote troubleshooting. For general information about remote troubleshooting, see the SMS version 1.2 Administrator's Guide.

The settings in the [Sight] section of the SMS.INI file on each client specify which remote troubleshooting utilities, if any, are enabled on the client. Users can modify these settings with the Help Desk Options program in the SMS Client program group. The remote troubleshooting agents and programs check the [Sight] section of the SMS.INI file for configuration settings. For more information about the SMS.INI file, see Chapter 4, "File Formats."

For all clients in the SMS inventory, the SMS Administrator uses the SIGHTNT.DLL program to obtain the computer address and the address type (a NetBIOS name or an IP or IPX address) from the database. When the Help Desk or Diagnostics icon is selected, SIGHTNT.DLL tries to connect to the client over a supported protocol (IP, IPX, or a NetBIOS protocol). Global defaults (such as time-out values for various NetBIOS Lana numbers and the IPX protocol) are stored in the Windows NT registry on the site server, under the following key:

HKEY_Local_Machine\Software\Microsoft\SMS\Components\SightNT


Remote Troubleshooting Across a RAS Connection

If the site address for a client is a RAS address, SMS uses GATEWAY.DLL to make an automatic RAS connection and gain access to the client. GATEWAY.DLL initiates the RAS connection to the remote LAN and authenticates the user by communicating with a RAS server that exists on the same LAN as the client. When a remote troubleshooting utility terminates, GATEWAY.DLL disconnects the target LAN, closes the RAS session, and frees up the port and modem.

The SMS remote troubleshooting utilities only support NetBIOS transports and IP across RAS. IPX transports are not supported. Also, GATEWAY.DLL does not support the SNA Sender and, for SNA links, will return the message Can't connect via SNA to SIGHTNT.DLL.


Remote Troubleshooting Across a WAN

You can remotely control clients across a bridged or routed WAN. In a bridged WAN environment, you can establish the remote control session over both NetBIOS-based and socket-based protocols. However, in a routed WAN environment, you cannot use NetBIOS-based protocols unless you also configure name management for the protocol.

For instance, Windows NT supports socket-based TCP/IP and NetBIOS-based TCP/IP. NetBIOS-based TCP/IP (NBT) can locate resources on a local IP network by name. However, resources located on remote subnets are not responsive to name query requests because routers do not pass IP-level broadcasts. For that reason, Windows NT uses a LMHOSTS file to map IP addresses to the NetBIOS names of computers outside the local subnet. LMHOSTS is a text file located in the winntsystemroot\SYSTEM32\DRIVERS\ETC directory. To remotely control an SMS client using NBT, a remote address must be matched with an entry in the TCP/IP LMHOSTS file on the SMS Administrator computer.

At start up, Windows NT reads LMHOSTS and stores entries in a system cache. NBT reads its internal cache. If no match is found, it sends a NetBIOS broadcast and retries the broadcast up to five times. If there is no response, NBT reads the LMHOSTS file directly. If it finds an entry for the computer name and corresponding remote IP address, NBT sends a datagram to that address. The query includes the address of the originating computer running Windows NT. When the target NetBIOS client receives the query, it sends a return packet to that address.


Chapter 4 - File Formats

Microsoft Systems Management Server (SMS) uses files to identify and configure clients, servers, domains, sites, packages, and so on. The files are maintained by various SMS components. Some files are in binary format, and thus cannot be viewed or edited. Other files are in text format; it is possible to view and even edit these files, although in general you should not modify SMS system files.

Text-based files that can be viewed and potentially modified are described in this chapter. For a complete listing of the files used by SMS servers, see Chapter 1, "Server Reference." For a complete listing of the files used by SMS clients, see Chapter 2, "Client Reference."

Note

Documentation of SMS system files is included for informational purposes only. You should not attempt to modify any of the system files that are maintained or used directly by SMS.

The file formats for the following text-based files are described in this chapter:

  • SMS.INI
  • Site control file
  • SYSTEM.MAP
  • Package and audit rule files
  • Package definition files
  • Management Information Format files
  • SNMP export files
  • Event to Trap Translator configuration tool format files
  • Client configuration request files


SMS.INI

The SMS.INI file is installed on all computers when they are added to the SMS system. This file stores system information about the client and the SMS site in which it is contained. SMS Client Setup creates the SMS.INI file, however the file is maintained and used by all of the SMS client components. The SMS.INI file is located in the root of the first (alphabetical) local hard drive (usually drive C).

SMS.INI is created from a master template file named DOMAIN.INI, which is located in the LOGON.SRV directory (SMS_SHR) on all SMS logon servers. The DOMAIN.INI file contains a subset of SMS.INI entries that are valid in the domain. When SMS Client Setup creates the SMS.INI file on a client, some of the values in the SMS.INI file are derived from the DOMAIN.INI file; other values are based on the specific configuration of the client.

The following sections and entries are in the SMS.INI file:

  • [Package Command Manager]
  • [Servers]
  • [Share]
  • [Program Group Control]
  • [AppCtlIniFiles]
  • [AppCtlScripts]
  • [MSTest16.20]
  • [WorkstationStatus]
  • [SMS]
  • [SMSLSIni]
  • [Local]
  • [Sight]
  • [LogonHistory]
  • [UserName]
  • [AppleServers]

These sections and entries are described in the following sections. In addition, a sample SMS.INI file is included in "Sample SMS.INI File" later in this chapter.

[Package Command Manager]

Information used by the Package Command Manager to locate its instruction files, results directory, and local status file.

InstructionSharePoint

The location of the Package Command Manager instruction files on the SMS logon server. The location is a subdirectory of the SMS logon server share.

ResultSharePoint

The location where the Inventory Agent places results of Package Command Manager actions.

LocalRegistryLocation

The location of the registry file (PCMHIST.REG) used by the Package Command Manager to store package information.

PollingInterval

Specifies how often (in minutes) the Package Command Manager checks for new packages. This value is the polling interval that is set in the Site Properties window of the SMS Administrator. If a value for PollingInterval is set in the [Local] section of SMS.INI, it overrides this value.

[Servers]

The servers available to the client components. These servers are SMS logon servers in the client domain. The client components use the entries in this section to determine where to read instructions or configuration information. In addition, these entries are used to determine where to send inventory and status information. Each server is listed as a separate entry in this section.

Domain

The name of the domain that processed the current user's logon request.

CurrentLogonServer

The name of the server that processed the current user's logon request.

Servernumber

The name of a server that acts as a collection point for the current client. The number identifies each server entry (for example, Server1, Server2, and so on).

[Share]

The shares to be used by the SMS client components. Each entry corresponds to an entry in the [Servers] section.

CurrentLogonServer

The share name on the current SMS logon server. On servers running Windows NT Server, LAN Manager, and LAN Server, this share is named SMS_SHR. On servers running NetWare, this entry specifies the volume name.

Servernumber

The share name for the corresponding server listed in the [Servers] section.

[Program Group Control]

The location of the files that store the configuration information for SMS network applications. Program Group Control reads configuration information from the files and uses it to configure and run SMS network applications.

Directory

The name of the directory containing the SMS network application files. The directory is relative to a server specified in the [Servers] section and the corresponding share name specified in the [Share] section.

[AppCtlIniFiles]

The location of the initialization files required by SMS network application configuration scripts. If an application requires a local copy of an initialization file, the configuration script can copy the file from this location to the local client.

Directory

The name of the directory containing the initialization files. The directory is relative to a server specified in the [Servers] section and the corresponding share name specified in the [Share] section.

[AppCtlScripts]

The location of the SMS network application configuration scripts. If an application requires a configuration script, the Application Control program looks for its configuration script at this location and runs it.

Directory

The name of the directory containing the configuration scripts. The directory is relative to a server specified in the [Servers] section and the corresponding share name specified in the [Share] section.

[MSTest16.20]

The location of the Package Command Manager installation scripts and SMS network application configuration scripts that are provided with SMS. This directory contains all default script processors.

Directory

The name of the directory containing the default script processors. The directory is relative to a server specified in the [Servers] section and the corresponding share name specified in the [Share] section.

[WorkstationStatus]

Indicates the client status.

SysFilesNotModified

Lists files, such as AUTOEXEC.BAT and WIN.INI, that SMS Client Setup could not modify. This indicates an error condition.

FilesNotDownloaded

Lists files that SMS Client Setup could not download. This indicates an error condition.

InstalledComponents

Indicates components installed on the client.

AutoStartComponents

Indicates components that are automatically started on the client.

StandaloneWorkstation

Reserved. Should be set to NO.

FailedHardwareChecks

Lists any hardware failures encountered during the inventory process. These failures are also listed in the SMSSAFE.TMP file. For more information about SMSSAFE, see Chapter 2, "Client Reference."

[SMS]

The information that identifies the client and maintains its inventory.

BuildNo

The SMS product build number. This number is compared to the build number in the DOMAIN.INI file on the SMS logon server. If the build numbers differ, the client software is automatically upgraded.

SPNumber

The SMS Service Pack number.

INIFileVersion

The version reference of the INI file. The higher 16 bits are the actual INI file version; the lower 16 bits are the build number.

CopyListVersion

The version reference of the copy-list file.

SiteCode

The three-character code identifying the site that maintains the current client's inventory.

SMS Unique ID

The client's system identifier, which is included in RAW files sent to the SMS logon server. The ID consists of a three-character site code followed by a five-digit number, such as TTT00003.

SMSPath

The client directory that contains SMS files and directories. Package Command Manager, Program Group Control, Program Group Control Start, SMSRUN, and the Inventory Agent read this path from SMS.INI.

SMSBinPath

The client directory that contains the SMS binaries.

StandaloneISVMIFPath

The directory path containing standalone MIF files. Objects defined by standalone MIF files have a custom architecture and are not included in the client's inventory (displayed in the Inventory window and the Personal Computer Properties - [computername] window). Instead, these standalone MIF objects are added to the SMS system database using their own architecture. They are stored and handled separately from the computer inventory. The Inventory Agent uses this path to locate the MIF files.

MachineISVMIFPath

The path to the directory containing client MIF files. These MIF files add new types of objects (such as new types of hardware) to the client's inventory. The objects are appended to the client architecture as a new group. These objects are included in the client's inventory and can be viewed in the Personal Computer Properties - [computername] window for the client. The Inventory Agent uses this path to locate the MIF files.

LocalWindowsPath

The path to the directory that contains the WIN.INI and SYSTEM.INI files (if found).

SharedWindowsPath

The path to the directory that contains Windows operating system files.

SMSLogPath

The path to the directory that contains the SMS client log files.

SMSDataPath

The path to the directory that contains data files used by the SMS binaries.

SMSInvDataPath

The path to the directory that is used to store inventory data files (Windows NT-based clients only).

SMSTempPath

Reserved.

SMSLocalTempPath

Reserved.

SharedWindowsBinaries

Reserved.

SharedSMSBinaries

Reserved.

ModifyAutoexecBat

Reserved.

LogonRoot

The path on a NetWare server between the volume name and the LOGON.SRV directory (including LOGON.SRV).

LastLogonServerPath

Indicates the relative path (\\servername\sharename) of the SMS logon server that last ran SMS Client Setup.

UniqueIdPath

The path to the unique ID file. This file is used to generate unique IDs.

LastSoftwareScan

The actual date and time that the software inventory was scanned.

LastHardwareScan

The actual date and time that the hardware inventory was scanned.

SoftwareScanInterval

By default, this setting is equivalent to the Software Inventory Frequency setting in the Inventory dialog box of Site Properties. A zero (0) indicates the software is scanned each time the Inventory Agent runs.

HardwareScanInterval

By default, this setting is equivalent to the Hardware Inventory Frequency setting in the Inventory dialog box of Site Properties. A zero (0) indicates the hardware is scanned each time the Inventory Agent runs.

InvAgtFalseLogonCount

The number of times it takes to log on to another site/domain before inventory is taken.

InventoryCollectionPoint (client only)

The path to the directory on the logon server where the Inventory Agent places inventory files.

SlowNetFlag

Determines when a slow network link, such as a RAS link, exists between the SMS logon server and the client. If a slow link is present, the Package Command Manager prompts the user to make selective decisions regarding software installation.

OS

The operating system that the client uses. If SMS Client Setup finds that this key is different from the operating system currently running, it prints a message and exits. The following values are possible:

Number | Meaning
1 | MS-DOS
2 | Windows 3.x
3 | OS/2
4 | Windows NT
5 | Windows 95

InventoryConfigurationPath

Path (relative to the LOGON.SRV directory) to the resync files on a Windows NT-based computer.

ConfigurationRequestPath

Path (relative to the LOGON.SRV directory) to the client configuration request files on a Windows NT-based computer.

ISVMIFCollectionPoint

For OS/2 and Macintosh clients, the directory where the Inventory Agent places inventory MIF files. By default, the directory is ISVMIF.BOX.

InvAgtServiceWakeupInterval

Specifies how often the Inventory Agent services for Windows NT and OS/2 wake up and check to see if the inventory frequency interval has elapsed. By default, the InvAgtServiceWakeupInterval value is 24 hours (1440 minutes).

CompanyName

The company name entered when SMS was installed at the local site.

NetworkType

Refers to the type of network software used by the SMS logon server. The following values are possible:

Number | Meaning
1 | Unknown
2 | Windows NT
3 | LAN Manager version 1.x
4 | LAN Manager version 2.x (includes WFWNET)
5 | NetWare 2.x
6 | NetWare 3.x
7 | NetWare 4.x

[SMSLSIni]

Added by SETLS when domain mapping of clients is enabled.

ValidatingServer

The name of the current SMS logon server.

FileName

The name of the file that contains the domain mappings. By default, this file is named SMSLS.INI.

FileTime

The time stamp of the domain mapping file. This time stamp is used to determine if any domain mapping changes have been made.

SectionMatch

The section in the mapping file that was used to map the client.

KeyMatch

The value of the section in the mapping file that was used to map the client.

Domain

The SMS domain that the client was mapped to as a result of the mapping file.

[Local]

Specifies the local Package Command Manager configuration. These settings are modified in the Package Command Manager Options dialog box.

SetupPhase

Indicates the present state of SMS (INSTALLED, UPGRADE, VERIFY_FILES, COMPONENT_DEINSTALL, DEINSTALL) on the client. SMS Client Setup writes this entry and checks it the next time it runs. SMSRUN uses this entry to maintain clients.

LanguageCode

Identifies the language version of the SMS client. This entry is written by SMS Client Setup.

NetCardID

The network card ID number as obtained by the Inventory Agent.

MachineName

The network computer name as obtained by the Inventory Agent.

SystemRole

The SMS system role. For example, server.

SystemType

The SMS system type. For example, x86-based personal computer.

LastPCMFileTime

Shows the most recent instruction file date used by Package Command Manager. The Package Command Manager checks this date to see if a new instruction file has arrived.

ShowPCMIntroDialog

Indicates whether the introductory message box should be displayed when Package Command Manager starts.

PollingInterval

A value set by the user to specify the Package Command Manager polling interval. If set, this value overrides the PollingInterval value specified in the [Package Command Manager] section.

UserName

Allows the user to enter a default name to be used by the Package Command Manager installation scripts.

CompanyName

Allows the user to override the default company name through which Package Command Manager installation scripts specify a company name when installing software.

NextAvailableSiteSMSUniqueID

This entry resides on the site server only. It is only written when a site is removed. This entry indicates the next available SMS unique ID that can safely be used. If the site is installed again with the same site code, this number is used as the starting point for all future SMS unique IDs.

[Sight]

Contains settings for remote control options. Some of these settings can be modified in the Help Desk Options dialog box.

Allow Takeover

Allows the computer running the SMS Administrator to take remote control of the client.

Allow Reboot

Allows the computer running the SMS Administrator to remotely restart the client.

Allow File Transfer

Allows file transfer to and from the client.

Allow Chat

Allows the Remote Chat utility to run.

Allow Remote Execute

Allows the computer running the SMS Administrator to remotely run programs on the client.

Visible Signal

Provides a visible signal to the user to indicate that the client is being controlled remotely.

Audible Signal

Provides an audible signal to the user to indicate that the client is being controlled remotely.

Allow Ping Test

Allows the computer running the SMS Administrator to remotely ping the client.

Allow DOS Diagnostics

Allows the computer running the SMS Administrator to remotely run the MS-DOS diagnostics utilities on the client.

Allow Windows Diagnostics

Allows the computer running the SMS Administrator to remotely run the Windows-based diagnostics utilities on the client.

Permission Required

Specifies whether the administrator running the SMS Administrator needs permission to remotely control the client.

Force Name

When set to yes, the computer name used between SMS and the client can be different from the LAN Manager computer name. If Force Name is set to yes, a MachineName entry must also be listed in the [Local] section.

Default Protocol

Default network protocol to be used for remote control. Valid protocols are NetBIOS, IP, and IPX.

LANANUM

Default Lana number to be used for remote control. Only valid for remote control over a NetBIOS protocol.

InstallWin16RCTSR

Indicates whether the remote control TSR (USERTSR / USERIPX) should be installed. Applies only to clients running Windows 3.1 (any network) or Windows for Workgroups (NetWare).

[LogonHistory]

Keeps track of logon attempts to another site or SMS domain. This information is used to determine if and when a computer's inventory should be reported to a new site or domain.

LastLoggedUser

The user name of the last user to log on to the network at the client.

Entry

When a user attempts to log on to a different site or SMS domain, this entry is used to store the last site or SMS domain where the client logged on. When the number of logon attempts reaches the number specified for InvAgtFalseLogonCount (in the [SMS] section), this entry is cleared.

Counter

Keeps track of the number of logon attempts to a different site or SMS domain. When the counter reaches the number specified for InvAgtFalseLogonCount, inventory is taken, and the computer is added to the new site/domain.

InventoryEntity

Specifies whether the Inventory Agent runs as a service or as an executable. Applies only to computers running Windows NT.

[UserName]

This user logon information is used for two purposes:

  • SMS Client Setup uses this information to create unique, friendly names for NetWare clients. Since NetWare clients don't have friendly computer names, the name is created by combining the user name and IPX address. If another user logs on at the computer, inventory is skipped until the third logon attempt. At that time, the computer name is changed to reflect the new user name. When the computer name is changed, SMS creates a new inventory record for the computer.
  • This information is also used to determine if and when a computer's inventory should be reported to a new site or domain.

The following keys are possible:

Current

The name of the user currently logged on at the client.

LastLoggedUser

The name of the previous user that logged on at the client.

Counter

The number of times that the current user has logged on at the client.

[AppleServers]

The servers available for Macintosh clients.

CurrentLogonServer

The name of the zone and server that processed the current user's logon request.

Servernumber

The name of the zone and server that acts as a collection point for the current client. The number identifies each server entry (for example, Server1, Server2, and so on).


Sample SMS.INI File

[Package Command Manager]
InstructionSharePoint=pcmins.box
ResultSharePoint=despoolr.box
LocalRegistryLocation=C:\MS\SMS\DATA\pcmhist.reg
PollingInterval=60

[Servers]
Domain=S1DOMAIN
CurrentLogonServer=STEVEBDC
Server1=STEVEBDC
Server2=STEVEPDC

[Share]
CurrentLogonServer=SMS_SHR
Server1=SMS_SHR
Server2=SMS_SHR

[Program Group Control]
directory=appctl.box\database

[AppCtlIniFiles]
directory=appctl.box\inifiles

[AppCtlScripts]
directory=appctl.box\scripts

[MSTest16.20]
directory=mstest

[WorkstationStatus]
SysFilesNotModified=
FilesNotDownloaded=
InstalledComponents=PCM, MIFENTRY, APPCONTROL, REMOTE_CONTROL
AutoStartComponents=PCM, MIFENTRY, APPCONTROL
StandaloneWorkstation=No

[SMS]
BuildNo=786
SPNumber=0
INIFileVersion=66302
CopyListVersion=835643765
SiteCode=SKZ
SMS Unique ID=SKZ01000
SMSPath=C:\MS\SMS
SMSBinPath=C:\MS\SMS\BIN
StandaloneISVMIFPath=C:\MS\SMS\idmifs
MachineISVMIFPath=C:\MS\SMS\noidmifs
LocalWindowsPath=C:\NT351
SharedWindowsPath=C:\NT351
SMSLogPath=C:\MS\SMS\LOGS
SMSDataPath=C:\MS\SMS\DATA
SMSInvDataPath=C:\MS\SMS\INVDATA
SMSTempPath=C:\MS\SMS\TEMP
SMSLocalTempPath=C:\MS\SMS\TEMP
SharedWindowsBinaries=No
SharedSMSBinaries=No
ModifyAutoexecBat=Yes
LogonRoot=
LastLogonServerPath=\\STEVEPDC\SMS_SHR
UniqueIdPath=\\STEVEPDC\SMS_SHR\SMSID\
LastSoftwareScan=19960715135536.000000+000
LastHardwareScan=19960715135536.000000+000
SoftwareScanInterval=0
HardwareScanInterval=0
InvAgtFalseLogonCount=3
InventoryCollectionPoint=inventry.box
SlowNetFlag=no
OS=4
InventoryConfigurationPath=invencfg.box
ConfigurationRequestPath=ccr.box
ISVMIFCollectionPoint=isvmif.box
InvAgtServiceWakeupInterval=1440
CompanyName=MS
NetworkType=2

[Local]
SetupPhase=installed
LanguageCode=00000409
NetCardID=52:41:53:48:00:01
MachineName=STEVEK1
SystemRole=Workstation
SystemType=X86-based PC
ShowPCMIntroDialog=FALSE
LastPCMFileTime=837217035

 [Sight]
Allow Takeover=Yes
Allow Reboot=Yes
Allow File Transfer=Yes
Allow Chat=Yes
Allow Remote Execute=Yes
Visible Signal=Yes
Audible Signal=Yes
Allow Ping Test=No
Allow DOS Diagnostics=No
Allow Windows Diagnostics=No
Permission Required=Yes

[SMSLSIni]
ValidatingServer=\\stevepdc
FileName=\\RED1\NETLOGON\smsls.ini
FileTime=300cafc8
SectionMatch=WIN.INI
KeyMatch=S1DOMAIN
Domain=S1DOMAIN

[LogonHistory]
LastLoggedUser=stevek
Entry=
Counter=0
InventoryEntity=EXE


Site Control File

The site control file provides a record of site configuration parameters. Each primary and secondary site has a unique master site control file (SITECTRL.CT0) located in the SMS\SITE.SRV\SITECFG.BOX directory. This file defines the site properties, including information such as the type of site, SMS service and SQL Server accounts, SMS domains and logon servers, SMS services and components, and specific site configuration options, such as inventory scanning intervals and SMS Client Setup options.

When site properties are modified, the Hierarchy Manager creates a temporary site control file (*.CT1), which is read by the Site Configuration Manager. The Site Configuration Manager overwrites SITECTRL.CT0 with the information in *.CT1 and creates another file named *.CT2, which is used to update the database.

The site control file begins with a line indicating the SMS build number and the syntax version number. For example:

SITE CONTROL FILE [786][1.08]

Additional sections then are used to define specific site properties. Section names in the site control file are typically grouped with a BEGIN and an END statement. For example, the following section defines the File Definition:

BEGIN_FILE_DEFINITION
  <2>
  <Setup-based site creation>
  <SKZ>
  <SKZ>
  <837492602>
  <1>
END_FILE_DEFINITION

The following sections and entries are in the site control file:

  • FILE_DEFINITION
  • TRANSACTION
  • SITE_ACCOUNT
  • PROPERTY
  • PROPERTY_LIST
  • DOMAIN
  • ADDRESS
  • OUTBOX
  • SERVER
  • COMPONENT
  • SENDER

These sections and entries are described in the following sections. In addition, a sample site control file is included in "Sample Site Control File" later in this chapter.

FILE_DEFINITION

Provides information about the site control file.

File Type

The file type for site control can be one of the following:

File type | Description
Actual (1) | Refers to a version of the site control file that contains the actual status of the site after completing the most recent changes. Such a file usually has a .CT2 extension.
Proposed (2) | Refers to site control files that contain proposed changes for the site. These files have a .CT1 extension and are used by the Site Configuration Manager as a basis for reconfiguring the site.
New site (3) | Used by SMS Setup to instruct Site Configuration Manager to begin creating a new site, either locally or remotely.
Transactions (4) | Contains specific one-time instructions for the Site Configuration Manager. These files initiate changes to the site hierarchy.
Local transactions (5) | Used by the Site Configuration Manager, Hierarchy Manager, and SMS Setup to pass along site upgrade or removal instructions within a site.

Comment

The description of the operation that generated the file. For example:

   Setup-based site creation

Target site

The site code for the site being modified.

Originating Site

The site code for the site that originated the site modifications.

GMT time stamp

The file creation time (using Greenwich Mean Time).

Posted/Not Posted

A value of 1 (posted) indicates that the file is used internally by the Hierarchy Manager. A 0 indicates no handling by the Hierarchy Manager.

TRANSACTION

A list of one-time transactions, usually a set of instructions to the Hierarchy Manager or Site Configuration Manager. If the file type is transactions only, this section will be the only other entry in the file. If there are no transactions to be done, this section is not present.

Transactions have the following format:

TRANSACTION<TransactionType><PersistentFlag><DWORDValue><String1><String2>

The TransactionType field is described in the following sections. The PersistentFlag field is used to indicate whether the transaction applies to all transactions or only to this transaction. The remaining 3 fields are data fields for the transactions.

The following transaction types are possible:

Change@

Transaction sent to change the SMS Service Account and password.

SqlChange@

Transaction sent to change the SQL Server account and password.

InactiveDomains, InactiveServers, InactiveComponents, InactiveSenders

These transactions are used by the Site Configuration Manager to report inactive items. A count of inactive items is displayed in the SMS Administrator; Windows NT and SMS events are also generated for each inactive item.

The first string in these transactions is a comma-separated list of up to 20 items. The second string is blank. The DWORD parameter gives a total count of inactive items of this type. For example:

   TRANSACTION InactiveDomains<0><2><DomainX,DomainY><>

DeinstallSite

Transaction sent to the Site Configuration Manager to remove the site from the site hierarchy.

InitiateDeinstall

Transaction sent to the Hierarchy Manager to initiate the removal of a site from the site hierarchy.

InitiateUpgrade

Transaction sent to the Hierarchy Manager to initiate a site upgrade.

DeinstallSiteAck

Transaction sent by the Site Configuration Manager to indicate that it has successfully removed a site from the site hierarchy.

Shutdown

Transaction sent to the Site Configuration Manager to shut down (stop and remove) all SMS services in the site.

ShutdownAck

Transaction sent by the Site Configuration Manager when shutdown is completed.

Upgrade

Transaction sent to the Site Configuration Manager to upgrade files for SMS services at the site.

DeleteSite

Transaction sent whenever a site needs to be deleted from the site hierarchy in all parent site databases. Each Hierarchy Manager forwards this to its parent site until the top of the tree is reached. The site is deleted only if the parent site code matches.

SyncParentDetach

Transaction used by the Hierarchy Manager to synchronize a detachment from a parent site.

ParentDetach

Transaction forwarded up the site hierarchy to detach from a parent site.

Heartbeat

Transaction sent in a site control file every 24 hours.

RequestNewSCFile

Transaction sent when the Site Configuration Manager detects no master site control file (SITECTRL.CT0).

TriggerWatchdog

Transaction that causes the Site Configuration Manager to do a watchdog cycle.

TriggerWatchdogHeartbeat

Transaction that causes the Site Configuration Manager to do a watchdog cycle and write a CT2 status file with a heartbeat transaction.

TriggerUserGroupMIF

Transaction that causes the Site Configuration Manager to do a watchdog cycle and write a user group MIF file.

TriggerLogonScriptConfig

Transaction that causes the Site Configuration Manager to do a watchdog cycle and modify logon scripts as specified by the Automatically Configure Logon Scripts setting.

LogEventForBootstrap

This transaction causes the Hierarchy Manager to log an event on behalf of the Bootstrap service.

SMSBaseID

Transaction sent by the Site Configuration Manager to log the last used SMS ID range from a previous SMS installation (if applicable).

NoEnumeration

Transaction sent to the Site Configuration Manager to suppress the enumeration of user groups.

SITE_ACCOUNT

Describes SMS account and configuration information.

SiteType

Defined by the following values:

Site Type | Value
9 | Secondary site
6 | Primary site

Site code

A three-character code that the SMS system uses to identify the site. The site code for any site must be unique across the SMS system. It is not case sensitive.

Parent site code

A three-character code that the SMS system uses to identify the parent site. This field is blank if the site does not have a parent site.

Site server

The name of the site server.

Site server domain

The Windows NT domain to which the site server belongs.

Site name

The name of the site.

Installation directory at the site

The path and directory name containing SMS files.

Service account domain name

The name of the domain that contains the SMS service account.

Service account name

The encrypted name for the SMS Service Account.

Password

The encrypted password for the SMS Service Account.

Public encryption key

The security mechanism used by SMS.

SQLServer name

The location of the SQL Server database that services the site.

SQL Login account

The encrypted login account for the SQL Server.

SQL Login password

The encrypted password for the SQL login account.

SQL database name

The name of the SQL Server database specified during SMS Setup.

SQL public encryption key

The security mechanism for SQL Server operations.

User name

The name the user entered during SMS Setup.

Organization

The name of the organization that the user entered during SMS Setup.

PROPERTY

Properties are various configurations used by different components. Property definitions include the property name followed two optional strings and a mandatory DWORD integer. (The DWORD value is 0 if there is no flag.) The following example uses two strings but no flag:

PROPERTY <User And Organization><AlexanderSeth><Siblings Inc><0>

Site Server Platform

The hardware platform (Intel, MIPs, RISC, and so on) of the site server. For example:

   <Site Server Platform><INTEL X86><><0>

Site Server Language

The language platform of the site server (English, French, and so on). For example:

   <Site Server Language><english><><0>

Last Valid @

The most recently known valid service password. The encrypted user name and password are defined by the first and second strings, respectively. The DWORD parameter contains the time stamp when the user name and password were created.

Last Valid SQL @

The last valid password for the SQL Server. The encrypted user name and password are defined by the first and second strings, respectively. The DWORD parameter contains the time stamp when the user name and password were created.

Hardware Scan/Software Scan

Two separate properties that define the frequency at which hardware and software scans occur. The frequency is defined using one of the following values:

Value | Scan frequency
1 (always) | A scan occurs each time a log on occurs.
2 (daily) | A scan occurs at most once a day.
3 (interval) | The property HardwareScanInterval (or SoftwareScanInterval) is also defined, and a scan occurs at most once during that interval.

Hardware Scan Interval/Software Scan Interval

Two separate properties that define the scan interval (in days).

User and Organization

The user name and company name specified during the site installation. For example:

   <User And Organization><SaraElizabeth><Siblings Inc><0>

SNA Local Address

Defines the local LU alias for the SNA Sender. For example:

   <SNA Local Address><MYLU1234><><0>

Note

When creating an LU alias for use with the SNA Sender, do not use numerals in the first position; numerals are allowed in positions 2 through 8 only.

Service Response

Indicates the monitoring mode for the SMS services. The faster the response rate, the heavier the system load. The following values are possible:

Value | Monitoring mode
1 | Test (1 minute)
2 | Fast (5 minutes)
3 | Medium (15 minutes)
4 | Slow (30 minutes)

Slow Net Strategy

Specifies how SMS clients at the site report their inventory when they have a slow communications link to their SMS logon server. This setting applies to all clients in the site. The following values are possible:

Value | Meaning
1 | Clients always report their inventory to the SMS logon server, even if the Inventory Agent detects a slow network.
2 | The Inventory Agent prompts the user if it detects a slow network. A message box requests permission for Inventory Agent to scan the client and report any inventory changes to the SMS logon server.
3 | The Inventory Agent does not scan when it detects a slow network.

Client Config Manager On Servers

Specifies where the Client Configuration Manager service is running. The following values are possible:

Flag | Meaning
0x00000001 | The Client Configuration Manager is automatically installed on the site server.
0x00000002 | The Client Configuration Manager is automatically installed on all SMS logon servers (if there is an agent for that type of server).
0x00000004 | The Client Configuration Manager is automatically installed on all helper servers.

Package Command Manager on Servers

Specifies where the Package Command Manager service is running. The following values are possible:

Flag | Meaning
0x00000001 | The Package Command Manager is automatically installed on the site server.
0x00000002 | The Package Command Manager is automatically installed on all SMS logon servers (if there is an agent for that type of server).
0x00000004 | The Package Command Manager is automatically installed on all helper servers.

Inventory Agent On Servers

Specifies where the Inventory Agent service is running. The following values are possible:

Flag | Meaning
0x00000001 | The Inventory Agent is automatically installed on the site server.
0x00000002 | The Inventory Agent is automatically installed on all SMS logon servers (if there is an agent for that type of server).
0x00000004 | The Inventory Agent is automatically installed on all helper servers.

PCM Polling

Specifies, in minutes, how frequently the Package Command Manager checks for new packages. This DWORD value applies to all clients but it can be overridden at an individual client through the Package Command Manager user interface.

LogonScripts

Indicates whether SMS is configured to alter logon scripts automatically. The following values are possible:

Flag | Meaning
0x00000000 | Do not automatically configure workstation logon scripts.
0x00000001 | The Automatically Configure Workstation Logon Scripts option is enabled.
0x00000002 | When existing logon scripts are automatically configured, SMS adds them at the bottom of the script.

Client Installation

Indicates whether SMS modifies the AUTOEXEC.BAT file on clients. The following values are possible:

Flag | Meaning
0x00000001 | Install Package Command Manager.
0x00000002 | Automatically start Package Command Manager.
0x00000008 | Install Program Group Control.
0x00000010 | Automatically start Program Group Control.
0x00000020 | Install Help Desk.
0x00000040 | Automatically start Help Desk.
0x00000100 | Install MIF Entry.
0x00000200 | Automatically start MIF Entry.

Version

The version of SMS software specified by SMS Setup. For example:

   <version><549><><0>

Default Package Server

Always set to Default Package Server.

Account Checking

Indicates whether SMS should attempt to validate the SMS Service Account before using it to install the SMS services. This property is currently used by SMS Setup only. The following values are possible:

Value | Meaning
1 | Account checking is enabled for the site.
0 | Account checking is disabled.

Remote Control Install Video Driver

Indicates whether or not to install support for the IDIS_NT.DLL remote control video driver.

Value | Meaning
0 | Do not install support for the remote control video driver.
1 | Install support for the remote control video driver.

Remote Control Command Line

Indicates the remote control command line to run on Windows NT clients. This command line lets you specify the default protocol and Lana number to be used on the clients.

GlobalUserGroupEnum

Indicates whether user group enumeration will be performed. The following values are possible:

Flag | Meaning
0x00000000 | Enumerate the user groups.
0x00000001 | Do not enumerate the user groups.

PROPERTY_LIST

Contains miscellaneous information about the site.

DOMAINTYPE

Supported domain types.

ADRSTRFMT

Supported sender address string types.

SoftwareUnits

Currently installed software units.

Remote Control Permitted Viewers

List of users and user groups that can remotely control Windows NT computers in the site.

Remote Control Supported Video Drivers

List of video adapters supported for accelerated screen transfer mode (valid only for computer running Windows NT).

NET_PROVIDERS

List of network provider types in the site. May include sub-lists.

Desktop Services

List of services installed on SMS logon servers.

Logon Script Files

A list of files used by the SMS logon script.

TrapFilter number

A description of each SNMP trap filter that has been defined in the site.

DOMAIN

Describes each SMS domain that participates in the site hierarchy.

Domain name

The name of the SMS domain.

Domain type

Specifies either Windows NT, LAN Manager, or NetWare.

Autoenumerate SMS logon servers

A 1 indicates that SMS is configured to autoenumerate SMS logon servers. A 2 indicates a user-defined list of servers and is followed by the SMS logon server list.

Logon server

SMS logon servers in the domain.

ADDRESS

Contains information about the site addresses. The format of the address string is:

ADDRESS <Originating Site Code><Destination Site Code><Sender Type><Address string format><Address String>

The sender type can be LAN Sender, SNA Sender, or RAS Sender. The address string format also refers to a sender type.

The address string begins with a number that indicates how many address characters are to be read in the rest of the string that follows. Most of the address string is encrypted because it contains passwords.

OUTBOX

An Outbox entry exists for each defined sender. The format of the outbox string is:

OUTBOX <Outboxname><Drive><Address string format><Schedule string> <CreateFlag><Server name>

SERVER

Various types of auxiliary servers are specified in this section. The format for the server string is:

SERVER <Server name><Server type><Flags><Install drive letter>

COMPONENT

Describes each of the Windows NT services (or their subcomponents) required by SMS.

Installation flags

The following table lists and describes the service installation flags.

Service | Flag | Description
INSTALL | 0x00000001 | Install this component.
LOCALSYSACCT | 0x00000002 | If this is a service, install it on the SMS logon server as a system account (instead of the SMS Service Account).
STARTSERVICE | 0x00000004 | Start this component if it is stopped.
SETREGISTRY | 0x00000008 | Configure the initial SMS registry values for this component.
EXE | 0x00000010 | Not currently used.
LITERALPATH | 0x00000020 | The file ID for this component is a full path to the executable file instead of an ID in the system map file.
PRIMARYSITE | 0x00000040 | Install this component if the site is a primary site.
SECONDARYSITE | 0x00000080 | Install this component if the site is a secondary site.
AUTOSTART | 0x00000100 | If this is a service, install it to start automatically during system startup.
SENDER | 0x00000200 | This component is a sender.
OPTIONALSVC | 0x00000400 | This component is optional at this site.
AS_THREAD | 0x00000800 | This component runs under the control of SMS Executive.
DONTSTOPSVC | 0x00001000 | This service is not stopped or removed during a site shutdown or site removal.

Service or thread name

The name of the service or component, such as SMS_EXECUTIVE or SMS_DESPOOLER.

File ID of the service or subcomponent

This ID is used to look up the list of file names in the system map file to determine the executable files (EXEs and DLLs) for this component.

Server on which to install the component

The name of the site server or a helper server where this component should be installed.

Drive on which to install the service

The drive letter to which the executable files are copied when the component is installed on the server named in the preceding entry.

SENDER

Describes the senders in use at the site. Senders are similar to components but have special characteristics, such as the type of address format they support and the outboxes they monitor.

Installation flags

See the Installation flags entry in "COMPONENT," earlier in this chapter.

Address string format type

The type of address format that this sender understands and, therefore, the type of outbox it uses. For example, MS_LAN_SENDER.

File ID of the sender

This ID is used to look up the list of file names in the system map file to determine the executable files (EXEs and DLLs) for the sender.

Drive on which to install

The drive letter where the executable files are copied to when the sender is installed on the server named in the next entry.

Server on which to install

The name of the site server or helper server where this sender should be installed.

Sender name

The name of the sender. For example, SMS_LAN_SENDER.

Outbox

The outbox the sender is monitoring.


Sample Site Control File

SITE CONTROL FILE [786][1.08]

BEGIN_FILE_DEFINITION
  <2>
  <Setup-based site creation>
  <SKZ>
  <SKZ>
  <837492602>
  <1>
END_FILE_DEFINITION

BEGIN_SITE_ACCOUNT
  <6>
  <SKZ>
  <>
  <STEVEPDC>
  <S1DOMAIN>
  <STEVE'S SITE>
  <D:\SMS>
  <S1DOMAIN>

  <348CF4B23D7AAA97E1A7B3AA0A6AC6928635E7D2D73153B170AD60DBD6399B3EC737DF552980A8>

  <98355E11DFCE1EAC93E29AAFD2D9D5A98512BD5D69B4C0295B38A1076A18FE00DF2B453CD0E6E9>
  <CEEBEA96831AABAB878E184E207C5C906D9E210404>
  <stevebdc>

  <448FF9F6711B80A74B8DD27549A3216CD120D2C726A390C639DE59CC3B4ED7868E7E3A862DB95F>

  <E411C8506516A50C6AFB7CBD2E7B1805A72ECB29ED5937882AD7539F71806BBACA705725EB8F10>
  <SMS>
  <9FD1B8FFE4FA969BAC0B6854349E7036E5C48E6CCE>
  <>
  <>
END_SITE_ACCOUNT

PROPERTY <Site Server Platform><INTEL X86><><0>
PROPERTY <Site Server Language><ENGLISH><><0>
PROPERTY <Last Valid @><><><831190761>
PROPERTY <Last Valid Sql @><><><831190761>
PROPERTY <Hardware Scan><><><1>
PROPERTY <Software Scan><><><1>
PROPERTY <Hardware Scan Interval><><><0>
PROPERTY <Software Scan Interval><><><0>
PROPERTY <User And Organization><Steve Kaye><MS><1>
PROPERTY <SNA Local Address><><><0>
PROPERTY <Service Response><><><1>
PROPERTY <Slow Net Strategy><><><1>
PROPERTY <CLIENT CONFIG MANAGER ON SERVERS><><><3>
PROPERTY <PACKAGE COMMAND MANAGER ON SERVERS><><><7>
PROPERTY <INVENTORY AGENT ON SERVERS><><><7>
PROPERTY <PCM Polling><><><60>
PROPERTY <Logon Scripts><><><0>
PROPERTY <Client Installation><><><891>
PROPERTY <Version><786><><0>
PROPERTY <Default Package Server><Default Package Server><><0>
PROPERTY <Account Checking><><><1>
PROPERTY <Remote Control Install Video Driver><><><1>
PROPERTY <Remote Control Command Line><-L0><><0>

BEGIN_PROPERTY_LIST
   <ADRSTRFMT>
   <MS_LAN_SENDER>
   <MS_BATCH_SNA_SENDER>
   <MS_INTER_SNA_SENDER>
   <MS_ASYNC_RAS_SENDER>
   <MS_ISDN_RAS_SENDER>
   <MS_X25_RAS_SENDER>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <Remote Control Permitted Viewers>
   <Administrators>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <Remote Control Supported Video Drivers>
   <ART>
   <FRAMEBUF>
   <MGA>
   <QV>
   <S3>
   <TGA>
   <VGA>
   <VGA256>
   <VGA64K>
   <WEITEKP9>
   <W32>
   <XGA>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <NET_PROVIDERS>
   <Microsoft Windows NT or LAN Manager, Dri&ve:,  15, 15, 2, 0x10000109 ,NETMSLM.DLL>
   <Novell NetWare,  &Volume:, 15, 48, 16, 0x20000204 ,NETNVNW.DLL>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <Novell NetWare>
   <>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <Microsoft Windows NT or LAN Manager>
   <PACKAGE COMMAND MANAGER ON SERVERS|WINDOWS NT 3.X=SMS_PACKAGE_COMMAND_MANAGER_NT>
   <INVENTORY AGENT ON SERVERS|WINDOWS NT 3.X=SMS_INVENTORY_AGENT_NT>
   <INVENTORY AGENT ON SERVERS|LAN MANAGER 2.X (OS/2)=SMS_INV_OS2LM>
   <CLIENT CONFIG MANAGER ON SERVERS|WINDOWS NT 3.X=SMS_CLIENT_CONFIG_MANAGER>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <DOMAINTYPE>
   <Novell NetWare>
   <Microsoft Windows NT or LAN Manager>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <Desktop Services>
   <INVENTORY AGENT ON SERVERS|0X00000007>
   <PACKAGE COMMAND MANAGER ON SERVERS|0X00000007>
   <CLIENT CONFIG MANAGER ON SERVERS|0X00000003>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <SoftwareUnits>
   <INTEL CLIENT>
   <SCRIPTS>
   <INTEL SERVER>
   <INTEL NETWORK MONITOR>
   <INTEL SMS ADMINISTRATOR>
   <ALPHA CLIENT>
   <ALPHA SERVER>
   <MIPS CLIENT>
   <MIPS SERVER>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <TrapFilter 0>
   <Valid 1>
   <Active 1>
   <IPAddress >
   <EnterpriseOID *>
   <GenericTrapID 16>
   <SpecificTrapID >
   <TrapAction 1>
   <Description Save Authentication Failure traps>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <TrapFilter 1>
   <Valid 1>
   <Active 1>
   <IPAddress >
   <NTEventSourceOID *>
   <GenericTrapID 127>
   <SpecificTrapID *>
   <TrapAction 1>
   <Description Save Windows NT Events>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <TrapFilter 2>
   <Valid 1>
   <Active 1>
   <IPAddress 123.123.123.123>
   <EnterpriseOID *>
   <GenericTrapID 127>
   <SpecificTrapID *>
   <TrapAction 1>
   <Description Save traps from Server TrafficCop>
END_PROPERTY_LIST

BEGIN_PROPERTY_LIST
   <TrapFilter 3>
   <Valid 1>
   <Active 1>
   <IPAddress >
   <EnterpriseOID *>
   <GenericTrapID 127>
   <SpecificTrapID *>
   <TrapAction 0>
   <Description Discard everything else>
END_PROPERTY_LIST

BEGIN_DOMAIN
  <S1DOMAIN>
  <Microsoft Windows NT or LAN Manager>
  <1>
  LOGONSERVER <STEVEBDC><><0><D:>
  LOGONSERVER <STEVEPDC><><0><D:>
END_DOMAIN

ADDRESS <SKZ><SKZ><MS_LAN_SENDER><LAN_DEFAULT>
  #182({}{\\STEVEPDC\SMS_SITE
348CF4B23D7AAA97E188E0407752F221FAE8ECD62E76BF6355E1F8CE113DFC85DCE587F15F7CB3

98355E11DFCE1E33390B0992F20A40BB44F7D58EB3E3381D0E800B3C06AC203576DA4D1BCDA1AA})

ADDRESS <SKZ><DF1><MS_LAN_SENDER><>
  #185({}{\\ASSIMILATOR1\SMS_SITE
359BFFA27F67A180F408A57531D7596CA854DAC021D993C74AD920B34B33D0F18E064EFE2DC02B

9A355E11DF6FDA7C17FC0BBD560F6005DE5AC32EEA23348959D02AE001FD6CCDCA08235DEBF664})

OUTBOX <LAN_DEFAULT><><MS_LAN_SENDER>

<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
OUTBOX <SNA_BATCH_DEFAULT><><MS_BATCH_SNA_SENDER>

<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
OUTBOX <SNA_INTER_DEFAULT><><MS_INTER_SNA_SENDER>

<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
OUTBOX <RAS_ASYNC_DEFAULT><><MS_ASYNC_RAS_SENDER>

<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
OUTBOX <RAS_ISDN_DEFAULT><><MS_ISDN_RAS_SENDER>

<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
OUTBOX <RAS_X25_DEFAULT><><MS_X25_RAS_SENDER>
<FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF

FFFFFFFFFFFFFFFF><1><D><STEVEPDC>
SERVER <STEVEPDC><Default Package Server><0><>

BEGIN_COMPONENT
  <2125>
  <SMS_ALERTER>
  <ALERTER.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2125>
  <SMS_TRAP_FILTER>
  <TRAPFLTR.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <77>
  <SMS_HIERARCHY_MANAGER>
  <PREINST.EXE>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_APPLICATIONS_MANAGER>
  <APPMGR.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <457>
  <SMS_SITE_CONFIG_MANAGER>
  <SITEINS.EXE>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <205>
  <SMS_EXECUTIVE>
  <SMSEXEC.EXE>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_MAINTENANCE_MANAGER>
  <MAINTAIN.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_SITE_REPORTER>
  <SITEREP.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_SCHEDULER>
  <SCHED.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2125>
  <SMS_INVENTORY_DATA_LOADER>
  <DATALDR.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_INVENTORY_PROCESSOR>
  <INVPROC.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_COMPONENT
  <2253>
  <SMS_DESPOOLER>
  <DESPOOL.DLL>
  <STEVEPDC>
  <D>
END_COMPONENT

BEGIN_SENDER
  <2765>
  <MS_LAN_SENDER>
  <SENDER.DLL>
  <D>
  <STEVEPDC>
  <SMS_LAN_SENDER>
  OUTBOX <LAN_DEFAULT>
END_SENDER


SYSTEM.MAP

The SYSTEM.MAP file lists the platforms, languages, directories, and files that SMS can use. It tells SMS Setup which directories to create for specific language IDs and platforms. SMS Setup uses the SYSTEM.MAP file to copy files and directories from the Microsoft Systems Management Server version 1.2 compact disc to the site server disk. The Maintenance Manager uses the SYSTEM.MAP file to create copy-list files; these files are used to specify the files that should be copied to clients. Copy-list files are copied to each type of client that SMS supports.

The SYSTEM.MAP file is located in the SMSSETUP directory on the Microsoft Systems Management Server version 1.2 compact disc. For an installed site, it is located in the SMS root directory on the site server. Because the SYSTEM.MAP file is used by SMS to control site configuration, this file should not be modified.

The SYSTEM.MAP file contains the following sections:

  • Platforms
  • Copylists
  • Languages
  • Units
  • IDList
  • Service
  • Package
  • Directories

These sections provide mappings from one or more items to a single keyword; for instance, the following IDList maps the substrings that can be used to indicate the Intel x86 platform:

IDLIST "INTEL X86" = "386", "486", "PENTIUM", "X86"

The sections in the SYSTEM.MAP file are described next.

Platforms

List of supported platforms (CPU architectures). SMS 1.2 supports Intel, DEC Alpha, MIPS, and Macintosh platforms. This is indicated in the following line which appears in the SYSTEM.MAP file for the U.S. English version of SMS 1.2:

   PLATFORMS = "INTEL X86", "DEC ALPHA", "MIPS R4000", "MAC 68000"

Copylists

Each entry indicates a client group for which files must be copied. For instance, in the following COPYLISTS section, the WIN95:PCM entry indicates the copy-list to be used to copy files to a Windows 95 client if the Package Command Manager is to be installed.

The COPYLISTS entry from the SMS version 1.2 SYSTEM.MAP file follows:

   COPYLISTS = "DOS:STANDARD", "DOS:PCM", "DOS:REMOTE_CONTROL",
   "DOS:REMOTE_CONTROL_386", "DOS:REMOTE_CONTROL_NETWARE",
   "DOS:REMOTE_CONTROL_LANMAN", "DOS:MIFENTRY", "WIN16:STANDARD",
   "WIN16:PCM", "WIN16:APPCONTROL", "WIN16:REMOTE_CONTROL",
   "WIN16:REMOTE_CONTROL_386", "WIN16:REMOTE_CONTROL_NETWARE",
   "WIN16:REMOTE_CONTROL_LANMAN", "WIN16:MIFENTRY", "WIN95:APPCONTROL",
   "WIN95:STANDARD", "WIN95:PCM", "WIN95:REMOTE_CONTROL",
   "WIN95:REMOTE_CONTROL_386", "WIN95:REMOTE_CONTROL_NETWARE",
   "WIN95:REMOTE_CONTROL_LANMAN", "WIN95:MIFENTRY", "WIN95:LANMAN",
   "WIN95:NETWARE", "OS2:STANDARD", "OS2:PCM", "OS2:MIFENTRY",
   "WINNT:REMOTE_CONTROL", "WINNT:STANDARD", "WINNT:PCM",
   "WINNT:APPCONTROL", "WINNT:MIFENTRY", "WIN16:LANMAN",
   "WIN16:NETWARE", "DOS:LANMAN", "DOS:NETWARE", "WINNT:LANMAN"

Languages

List of languages supported by this version of SMS. For example, the following line is included in the SYSTEM.MAP file for the U.S. English version of SMS 1.2:

   LANGUAGES = "ENGLISH"

Units

List of the valid installable software units for this version of SMS. This information is used by SMS Setup to properly configure the site. The UNITS entry from the SMS version 1.2 SYSTEM.MAP file follows:

   UNITS = "ALPHA SERVER", "MIPS SERVER", "INTEL SERVER", "INTEL CLIENT", "ALPHA CLIENT",

"MIPS CLIENT", "MACINTOSH CLIENT", "SCRIPTS", "INTEL SMS ADMINISTRATOR",

"ALPHA SMS ADMINISTRATOR", "MIPS SMS ADMINISTRATOR", "INTEL NETWORK MONITOR",

"ALPHA NETWORK MONITOR", "MIPS NETWORK MONITOR"

IDList

Define new associations to be used by the SMS system. For instance, IDLists define the default platforms, languages, CPU identifiers, directories, allowable installation or upgrade options, and so on. A sampling of the IDLists that appear in the SMS version 1.2 SYSTEM.MAP file follows:

   IDLIST "BUILDNUMBER" = "786"
   IDLIST "SPNUMBER" = ""
   IDLIST "SYSMAPVERSION" = "786", "FINAL", "SMS V1.2", "FULL"
   IDLIST "SMSVERSIONINFO" = "V1.2", "712"
   IDLIST "LANGUAGE_DEFAULT" = "ENGLISH"
   IDLIST "PLATFORM_DEFAULT" = "INTEL X86"
   IDLIST "PERMITTED_UPGRADES" = "479:479", "521:531", "531:786"
   IDLIST "INTEL X86" = "386", "486", "PENTIUM", "X86"
   IDLIST "DEC ALPHA" = "ALPHA", "DEC", "DIGITAL"
   IDLIST "MIPS R4000" = "R4000", "R4400", "MIPS", "RPC 44", "ARCSBIOS"
   IDLIST "MAC 68000" = "MAC", "APPLE", "68000"
   IDLIST "PLATFORM_DIRECTORY" = "INTEL X86=X86.BIN", "DEC ALPHA=ALPHA.BIN", "MIPS R4000=MIPS.BIN", "MAC 68000=MAC.BIN"

Service

Defines how to install the SMS services. The Service sections use the BEGIN and END keywords. They also use the FLAGS, MAIN, and SUBCOMPONENT keywords, as follows:

· The FLAGS keyword is used to indicate how the service should be installed and configured. See the following table to interpret the Flag bits.

· The MAIN keyword is used to indicate the primary executable file associated with the service or component.

· The SUBCOMPONENT keyword is used to indicate the secondary executable files associated with the service or component.

The following is an example of the Service entry for the SMS service, SMS_ASYNC_RAS_SENDER.

   SERVICE "SMS_ASYNC_RAS_SENDER"
   BEGIN
      FLAGS = 3789
      MAIN "SENDER.DLL"
      SUBCOMPONENT "CONNRAS.DLL"
   END

The following table lists the service flag bits.

Service | Flag | Description
INSTALL | 0x00000001 | Installs this component.
LOCALSYSACCT | 0x00000002 | If this is a service, installs it on the SMS logon server as a system account instead of the SMS Service Account.
STARTSERVICE | 0x00000004 | Starts this component if it is stopped.
SETREGISTRY | 0x00000008 | Configures the initial SMS registry values for this component.
EXE | 0x00000010 | Not currently used.
LITERALPATH | 0x00000020 | The file ID for this component is a full path to the executable file instead of an ID in the system map file.
PRIMARYSITE | 0x00000040 | Installs this component if the site is a primary site.
SECONDARYSITE | 0x00000080 | Installs this component if the site is a secondary site.
AUTOSTART | 0x00000100 | If this is a service, installs it to start during system startup.
SENDER | 0x00000200 | This component is a sender.
OPTIONALSVC | 0x00000400 | This component is optional at this site.
AS_THREAD | 0x00000800 | This component runs under the control of the SMS Executive.
DONTSTOPSVC | 0x00001000 | This service is not stopped or removed during a site shutdown or site removal.

Package

Defines how to install the SMS services on SMS logon servers and Windows NT-based clients. The Package section uses the BEGIN and END keywords. It also uses the FLAGS, MAIN, and SUBCOMPONENT keywords (see the preceding section for a description of how these keywords are used).

An example follows:

   PACKAGE "SMS_INVENTORY_AGENT_NT"
   BEGIN
      FLAGS = 0
      MAIN "INVWIN32.EXE"
   END

Directories

The remainder of the SYSTEM.MAP file consists of directories and files that must be created or installed on the site server. The directories and files are installed based on the microprocessor architecture platform, language, and software installable units specified in the section. For instance, the following section creates the PRIMSITE.SRV\AUDIT directory, and installs the files AUDIT.RUL and RUL2CFG.BAT in the directory:

   DIRECTORY "PRIMSITE.SRV\AUDIT"
   PLATFORM "" LANGUAGE "" SOURCE "COMMON\INTNL" FLAGS = 42
   UNIT = "SCRIPTS"
   BEGIN
      "AUDIT.RUL", SIZE(1, 1033292, 1033292), "AUDIT.RUL", "AUDIT.RU_", REMOTE=NO, COPYLISTS(), COMPRESS=NO, FLAGS = 1
      "RUL2CFG.BAT", SIZE(1, 991, 991), "RUL2CFG.BAT", "RUL2CFG.BA_", REMOTE=NO, COPYLISTS(), COMPRESS=NO, FLAGS = 1
   END


Package and Audit Rule Files

Package rule files and audit rule files are both used by SMS to determine information about the software installed on clients. Package rule files are used when SMS performs software inventory on clients. Audit rule files are used when SMS runs a special Run Command On Workstations job on clients (the job runs the Audit program and uses the audit rules in the audit rule file). For more information about software inventory and audit, see the SMS version 1.2 Concepts and Planning.

Although the software inventory process differs from the auditing process, the package rule file and the audit rule file have the same format. To simplify terminology in this chapter, the term package rule file will generally be used to refer to both software inventory rule files and to audit package rule files.

A package rule file is a text file that contains rules for identifying software installed on SMS clients. A package rule file must be converted into a binary (*.CFG) file before SMS can use the package rule file. When packages are enabled for software inventory, the Maintenance Manager automatically converts the package rule file into CFG format. When you want to perform an audit, you must manually convert the package rule file to CFG format using the RUL2CFG program.

The package rule file is a list of software items called packages. For each package, there is a set of rules that are used to identify it. Each rule is the name of a file and, optionally, a set of attributes for that file.

The definition of a package begins with the package keyword, a package ID, and a package name:

package packageID "packagename"

packageID

An integer that uniquely identifies the package within the package rule file. The packageID must be unique within the package rule file.

packagename

A string (enclosed in quotation marks) that serves as a text label for the package. This string is used for the Package Name attribute when the package is reported to the SMS inventory.

This package identification is followed by a list of files that identifies the package. Each file must have a file name. Optionally, you can specify additional attributes (such as file size, file date, checksum, and so on) for each file.

The file keyword is followed by the file name and the optional file attributes:

file "filename" [fileattributes]

filename

A string (enclosed in quotes) that specifies the name of the file. This can be an 8.3 file name or a long file name.

fileattributes

Can be one or more attributes of the file. Each type of attribute begins with a keyword followed by the specific value (or values) for the attribute. Numerical values and offset values (such as BYTE, CHECKSUM, and so on) must be specified in decimal rather than hexadecimal. These values can be determined in the SMS Administrator when you set up the package for inventory.

The following file attributes are possible:

BYTE

An 8-bit value stored at a specific location in the file.

BYTE offset value

where offset is the data offset from the start of file (in bytes); and value is the value (in decimal notation) stored at the location specified by offset.

CHECKSUM

The sum of all values stored at a specific set of bytes.

CHECKSUM offset length value

where offset is the data offset at the beginning of the summed values (in bytes); length is the total number of bytes that are summed; and value is the summed value (in decimal notation) of all values stored in the specific range of bytes.

COLLECT (for use with Inventory Agent only)

A keyword that tells the Inventory Agent to collect the file and send it with the computer's inventory. This keyword has no affect on the Software Audit program.

CRC

The sum (and sequence) of all values stored at a specific set of bytes. Unlike CHECKSUM, CRC takes into account the sequence of the summed bytes. This makes it a more reliable identification of a file.

CRC offset length value

where offset is the data offset at the beginning of the summed values (in bytes); length is the total number of bytes that are summed; and value is the summed value (calculated with the CCITT-CRC algorithm and specified in decimal notation) of all the values stored in the specified range of bytes. SMS uses the CCITT-CRC standard to evaluate the CRC value. You must specify a CRC value computed with the CCITT-CRC algorithm.

DATE

The date of the file.

DATE mm/dd/yy

where mm is the decimal value for the month; dd is the decimal value for the day; and yy is the decimal value for the year. Single digit months and days must have a leading zero (for example, 01/03/95).

LONG

A 4-byte (32-bit) value stored at a specific location in the file.

LONG offset value

where offset is the data offset (in bytes); and value is the 32-bit value (in decimal notation) stored at the offset.

SIZE

The size of the file (in bytes).

SIZE filesize

where filesize is the size of the file in bytes.

STRING (TOKEN)

A string value stored at a specific location in the file. It appears as STRING in the user interface and as TOKEN in PACKAGE.RUL.

STRING offset "string"

where offset is the data offset in bytes; and string is the string value stored at the location starting at offset. The string value must be enclosed in quotation marks.

TIME

The time associated with the file.

TIME hh:mm

where hh is the decimal value (using the 24-hour clock) for hours; and mm is the decimal value for minutes. Single digit hours and minutes must have a leading zero (for example, 01:05). Midnight is written as 00:00.

WORD

A 2 byte (16-bit) value stored at a specific location in the file.

WORD offset value

where offset is the data offset from the start of file (in bytes); and value is the 16-bit value (in decimal notation) stored at the location specified by offset.

You can specify up to four STRING/TOKEN values per file. You can only specify one value for all other attributes.


Combining File Rules

The list of files for a package can be combined together using the AND and the OR operators. If no operator is specified between adjacent files, the AND operator is used. AND has precedence over OR.

An AND clause is true when both expressions connected by the AND are true. An OR clause is true when either (or both) of the expressions connected by the OR are true.

The Inventory Agent and Software Audit program search for the files connected in an AND clause in a single directory. Therefore, in order for an AND clause to evaluate to true, all files specified in the AND clause must be found in the same directory. For example, the following package rule specifies two files connected by an AND operator:

PACKAGE 1 "Configuration Files"
  FILE "CONFIG.SYS"
  AND
  FILE "SYSTEM.INI"

When SMS evaluates this rule, if the two files are not found, or they are found but they exist in different directories, then the rule is evaluated to false, and the package is not detected. The example package would be found if CONFIG.SYS and SYSTEM.INI existed in the same directory (for example, in C:\BACKUP).

For files connected by an OR operator, one or both must exist in a directory for the package to be detected. For example, if a package is defined as two files connected by an OR operator and the two files exist in the same directory, one instance of the package is detected:

PACKAGE 1 "Configuration Files"
  FILE "CONFIG.SYS"
  OR
  FILE "SYSTEM.INI"

In the preceding example, if CONFIG.SYS is detected in C:\BACKUP and SYSTEM.INI is detected in C:\WINDOWS, two instances of the example package are detected, because the file rule evaluates to true in both directories.

As another example, consider the following package rule:

PACKAGE 1 "Corporate Accounting Application"
  FILE "CORAPP.EXE"
  OR
  FILE "CORAPP.DLL"
  FILE "COR3D.DLL"

Because there is no operator specified between the files CORAPP.DLL and COR3D.DLL, SMS uses the AND operator between these files. The package rule is evaluated as follows:

1. First, SMS processes the AND clause. It looks for the files COR3D.DLL and CORAPP.DLL. If found in the same directory, this clause evaluates as true. If the files are not found, or they are found in different directories, then this clause is false.

2. Next, SMS processes the OR clause. If the AND clause was true, then the OR clause is also true. If the AND clause was false, then SMS looks for the file CORAPP.EXE. If it finds this file in any directory, the OR clause is true. If the AND clause was false and the file CORAPP.EXE is not found, then the OR clause is false.


Using Parentheses to Group File Rules

You can use parentheses to group files together as a single entity. Groups have higher precedence than the AND and OR operators. You can use parentheses to clarify how a package rule with a mix of AND and OR operators will be evaluated.

For example, consider the following package rule:

PACKAGE 1 "Good MS-DOS and Windows Configuration"
  FILE "CONFIG.SYS"
  AND
  FILE "SYSTEM.INI"
  OR
  FILE "VER.DLL"

This rule contains no groups, and so SMS evaluates the AND clause (CONFIG.SYS AND SYSTEM.INI) and then the OR clause (OR VER.DLL). The package is detected if CONFIG.SYS and SYSTEM.INI are found in the same directory or if VER.DLL is found in any directory.

However, if you add parentheses to the rule as follows:

PACKAGE 1 "Good MS-DOS and Windows Configuration"
  FILE "CONFIG.SYS"
  AND
  (
    FILE "SYSTEM.INI"
    OR
    FILE "VER.DLL"
  )

SMS evaluates the OR clause in parentheses before it evaluates the AND clause. The package is detected if CONFIG.SYS is found in a directory and either SYSTEM.INI or VER.DLL is found in that same directory.


Using File Attributes to Create Complex Rules

In the preceding examples, the rules used only the filename to identify packages. In order to identify files more certainly, you can specify additional file attributes in the package rule. These attributes were described earlier in this chapter. The allowable file attributes are:

  • BYTE offset value
  • CHECKSUM offset length value
  • CRC offset length value
  • DATE mm/dd/yy
  • LONG offset value
  • SIZE filesize
  • STRING offset "string"
  • TIME hh:mm
  • WORD offset value

The following example uses the AND operator to detect a package if all three files (WINWOOD.EXE, WINWOOD.INI, and DIALOG.FON) are found on the client. It also requires that the WINWOOD.EXE file must have a filesize of 3483136 bytes, that the value of BYTE 10000 is 114, and that the CHECKSUM of the file (from byte 5000 to byte 5100) is 6851.

FILE winwood.exe  SIZE 3483136 BYTE 10000 114 CHECKSUM 5000 100 6851
AND
FILE winwood.ini
AND
FILE dialog.fon

Although this example includes only three files, and specifies file attributes for only one of the files, you can create rules which include many more files, and you can specify file attributes for all files in the package rule. For more package rule examples, look at some of the PDFs supplied with SMS version 1.2 (you can import the PDFs in the Packages window of the SMS Administrator). For more information about PDFs, see the following section.


Package Definition Files

A package definition file (PDF) is a text file that contains predefined Workstations, Sharing, and Inventory property settings for a package. When you create a new package, you can use the Import command from the Package Properties dialog box to define the properties for the package, using a PDF.

A PDF follows the standard *.INI file format. It is an ASCII text file containing keys (the key names are enclosed within brackets). Key names can be separated by spaces. Each key contains one or more entries, where each entry follows the format:

name = value1, value2, ...

Values are separated by a comma and at least one space.

A PDF has specific keys and entries that are used by the system to set the properties of a package. The following keys are allowed in a PDF file:

  • [PDF] (required)
  • [Package Definition] (required)
  • [SetupVariation Setup]
  • [Setup Package for Sharing]
  • [Program Item Properties Index] (required for shared applications)
  • [Setup Package for Inventory]
  • [File Index] (required for inventory)

These keys are described in the following sections. A sample PDF file is included at the end of this section.

[PDF] (required)

Identifies the file as a PDF. This section contains a single entry:

Version (required)

The version of the PDF format used by the file.

Example:

   Version = 1.0

[Package Definition] (required)

Defines the overall properties of the package.

Product (required)

The name of the product.

Example:

   Product = Microsoft Excel

Version (required)

The version of the product.

Example:

   Version = 4.0a

Comment

The comment used for the package's Comment setting. When the PDF is imported into SMS, this string is used as the Comment in the Package Properties dialog box.

Example:

   Comment = version 4.0a for Windows

SetupVariations (required for setting up workstation packages)

A list of the setup variations supported by the package. Each setup variation name corresponds to the [SetupVariation Setup] key, described in the following section.

Example:

   SetupVariations = Typical, Complete, Laptop, Automated

WorkstationAccess

The access permissions to the packages created with this PDF. You can assign either read or write permissions to the Users and the Guests groups. Thus, there are four permissions that you can assign:

UserRead

Permits users in the Users group to read and copy files, run programs, change directories within the shared directory, and read extended attributes of files.

GuestRead

Permits users in the Guests group to read and copy files, run programs, change directories within the shared directory, and read extended attributes of files.

UserWrite

Permits users in the Users group to write the contents and extended attributes of files.

GuestWrite

Permits users in the Guests group to write the contents and extended attributes of files.

To run a program file (that is, one with a .COM, .EXE, or .BAT extension), the user must have Read permission. The default is for both Users and Guests to have both Read and Write permissions.

Example:

   WorkstationAccess = UserRead, UserWrite, GuestRead

Note

The values for WorkstationAccess are case-sensitive; they must be specified exactly as shown in the preceding section.

[SetupVariation Setup]

For the setup variations specified in the SetupVariations entry in the [Package Definition] key (described in the preceding section), the PDF must have a key that defines each variation. For SMS, the setup variations specify the package commands that will be defined for the package's Workstations property. Typical setup variations for Microsoft applications include Typical, Complete, Laptop, and Automated setups.

CommandName (required)

The name used for this package command. When the PDF is imported into SMS, this string is used as the Command Name for this package command.

Example:

   CommandName = Automated Minimum Installation

CommandLine (required)

The command line used for this package command. When the PDF is imported into SMS, this string is used as the Command Line for this package command. The command should be relative to the package directory.

Example:

   CommandLine = setup.exe

SystemTask (required)

Specifies whether this package command can run in background mode on unattended computers running Windows NT. Specify TRUE if the command can be run as a system background task; FALSE if the command cannot be run as a system background task.

Example:

   SystemTask=TRUE

Note

If you wish to set SystemTask to TRUE, you must also set UserInputRequired (described in the following section) to FALSE. For both keys, the TRUE and FALSE values are case-sensitive and must be specified as all uppercase.

UserInputRequired (required)

Specifies whether this package command requires interaction with the user to complete the command. You can specify TRUE or FALSE.

Example:

   UserInputRequired = TRUE

SynchronousSystemExitRequired

The meaning of this key depends upon the client platform on which the package command is running.

On Windows-based clients, this key is used to automate package commands that require a system restart (typically these package commands set up applications). When this key is set to TRUE, Package Command Manager allows the application launched by the package command to restart the computer. When set to FALSE, Package Command Manager will not permit the launched application to restart the computer. If this key is not specified, it defaults to FALSE.

On MS-DOS clients, this key is used to provide additional memory for the application launched by the package command. When this key is set to TRUE, Package Command Manager launches the application specified by the package command and then ends. This allows more memory for the package command, but it also means that Package Command Manager does not regain control after the package command application ends. When this key is set to FALSE (or not specified), Package Command Manager remains loaded in memory and regains control after the package command application ends.

Example:

   SynchronousSystemExitRequired = FALSE

SupportedPlatforms (required)

Specifies the operating systems where the package can be installed and run. Each operating system name must be separated by a comma and a space. Supported platforms are MS-DOS, Windows 3.1, Windows95, Windows NT (x86), Windows NT (MIPS), Windows NT (Alpha), and Macintosh.

Note In previous versions of SMS, this key required a platform version for MS-DOS (for instance, MS-DOS 6.0) and for Windows NT (for instance, Windows NT 4.0 (x86)). In SMS version 1.2, the platform version is no longer required. PDFs that specify a version for these platforms will be accepted by SMS version 1.2, however the platform version will be discarded.

Example:

   SupportedPlatforms = Windows 3.1, Windows95, Windows NT (Alpha), Windows NT (MIPS), Windows NT (x86)

[Setup Package for Sharing]

Defines the Sharing properties of the package. Sharing properties are used for installing the package on servers and sharing it from those servers (Share Package On Server jobs).

ShareName (required)

The share name that you want to assign to the shared package when it is installed on a server.

Example:

   ShareName = exc40ash

ShareAccess (required)

The access permissions to the package's share when the shared package is installed on a server. You can assign either read or write permissions to the Users and the Guests groups. Thus, there are four permissions that you can assign:

UserRead

Permits users in the Users group to read and copy files, run programs, change directories within the shared directory, and read extended attributes of files.

GuestRead

Permits users in the Guests group to read and copy files, run programs, change directories within the shared directory, and read extended attributes of files.

UserWrite

Permits users in the Users group to write the contents and extended attributes of files.

GuestWrite

Permits users in the Guests group to write the contents and extended attributes of files.

Example:

   ShareAccess = UserRead, UserWrite, GuestRead, GuestWrite

Note

The values for ShareAccess are case-sensitive; they must be specified exactly as shown in the preceding section.

[Program Item Properties index] (required for shared applications)

Contains keys that are used to specify the program item properties for SMS network applications contained in the package. Each program item will be defined in the package's Sharing property. The value for index is a unique integer that identifies the program item within the PDF. The index should start at 1 and increase by 1 for each additional program item.

Description (required)

The program item description displayed to the user when they run the SMS network application. When the PDF is imported into SMS, this entry is used as the description for the program item.

Example:

   Description = Microsoft Excel

CommandLine (required)

The command used to start the SMS network application.

Example:

   CommandLine = EXCEL.EXE

ConfigurationScript (required)

The configuration script file used to configure the SMS network application at clients. This value can be NULL. If an explicit path is not specified, the package source directory is the default path to the configuration script.

Example:

   ConfigurationScript = exc40a0n.PCD

RegistryName (required)

The name of the key where the SMS network application's configuration information is stored in the Windows registry.

Example:

   RegistryName = EXCEL4

DefaultINIFile (required)

The file that the SMS network application uses as a default initialization file. Specify the filename only, not a path to the file. The specified INI file must be in the same directory as the PDF file.

Example:

   DefaultINIFile= EXCEL4.ini

RunMinimized (required)

Specifies whether the SMS network application should be minimized to an icon each time the user starts it by using the program item. You can specify TRUE or FALSE.

Example:

   RunMinimized = TRUE

RunLocalCopyIfPresent (required)

Specifies whether the SMS APPSTART program should search for the file specified by CommandLine locally in the client's path. If APPSTART finds the file, it starts the local version; otherwise, it starts the network version. You can specify TRUE or FALSE.

Example:

   RunLocalCopyIfPresent = TRUE

DriveMode (required)

Specifies how the SMS APPSTART program should connect to the server and shared directory where the SMS network application is located. You can specify one of three values:

UNC

APPSTART runs the SMS network application by using a UNC name. No drive letter is connected to the application's shared directory.

ANY_DRIVE_LETTER

APPSTART must connect to the application's shared directory by using a drive letter—but APPSTART can use any available drive letter on the client.

SPECIFIC_DRIVE_LETTER DriveLetter:

APPSTART must connect to the application's shared directory by using a specific drive letter. DriveLetter specifies the drive letter that APPSTART must use. The drive letter must be followed by a colon (:).

Note

All DriveMode values are case-sensitive and must be specified as all uppercase.

Example:

   DriveMode = SPECIFIC_DRIVE_LETTER W:

SupportedPlatforms (required)

Specifies the supported operating systems platforms on which the program item is to be made available. Separate the operating system names with commas. Supported platforms are MS-DOS, Windows 3.1, Windows95, Windows NT (x86), Windows NT (MIPS), Windows NT (Alpha), and Macintosh.

Note

In previous versions of SMS, this key required a platform version for MS-DOS (for instance, MS-DOS 6.0) and for Windows NT (for instance, Windows NT 4.0 (x86)). In SMS version 1.2, the platform version is no longer required. PDFs that specify a version for these platforms will be accepted by SMS version 1.2, however the platform version will be discarded.

Example:

   SupportedPlatforms = Windows 3.1, Windows95, MS-DOS, Macintosh

DisplayIconInProgGroup

Specifies whether an application icon is placed in a program group. This entry should be FALSE for utility applications, such as MSAPPS, that are to be distributed along with other SMS network applications.

Example:

   DisplayIconInProgGroup=FALSE

SetupIcon

Specifies the file containing the icon that you want to use for the SMS network application. This must be a *.ICO file.

Example:

   SetupIcon = exc40a01.ico

[Setup Package for Inventory]

Defines the Inventory properties for the package. The Inventory properties are used by the SMS system to maintain inventory on the package.

The SMS system identifies a package by searching for a set of files that you specify in the package's Inventory properties. For each file, you specify the attributes used to detect the file (such as file date, file size, CRC, and so on). If the Inventory Agent program detects files that satisfy the conditions set by the package's Inventory properties, the Inventory Agent reports that the package has been detected on the client.

Within the Inventory properties, you can also set an option that enables SMS to collect specified files from clients and store them on the site server.

InventoryThisPackage (required)

Specifies whether the package should be included in the SMS inventory. You can specify TRUE or FALSE.

Example:

   InventoryThisPackage = TRUE

Detection Rule Part index (required)

Specifies the inventory rule used to identify the package. A package's inventory rule is the set of files used to identify the package. Using the AND and OR operators, you can specify the set of files required to detect the package. The Part index indicates the order in which the rules are evaluated. The index should start at 1 and increase by 1 for each part of the rule.

For the files specified in the rule (except Boolean operators and grouping operators), the PDF must have a [File index] key. (This key is described in the next section).

You combine the file specifications by using the following rules:

  • Files are combined using AND and OR operators. AND has precedence over OR.
  • Files can be grouped and ungrouped with parentheses. Files within a group are treated as a single entity. For example, the rule File1 AND (File2 OR File3) specifies that SMS detects the package when File1 is found and either File2 or File3 is found—that is, File1 = TRUE and (File2 OR File3) = TRUE. Groups have precedence over AND and OR.

Example:

   Detection Rule Part 1 = File1
   Detection Rule Part 2 = AND
   Detection Rule Part 3 = File2
   Detection Rule Part 4 = OR
   Detection Rule Part 5 = (
   Detection Rule Part 6 = File3
   Detection Rule Part 7 = AND
   Detection Rule Part 8 = File4
   Detection Rule Part 9 = )

[File Index] (required for inventory)

For the files specified in the Detection Rule Part index entry in the [Setup Package for Inventory] key, the PDF must have a key that defines each file. Each file corresponds to a key that defines the attributes of the file. The value for index is a unique integer that identifies the file within the PDF and the inventory rule. The index should start at 1 and increase by 1 for each additional file.

The Filename is required. All other attributes are optional.

Filename (required)

The name of the file.

Example:

   Filename = EXCEL.EXE

Collect

Specifies whether the SMS system should collect a copy of this file and store it on the site server. You can specify TRUE or FALSE.

Example:

   Collect = FALSE

BYTE

Specifies a value stored at a specific location in the file. This attribute requires two entries (separated by a comma and a space):

· Location is the data offset in bytes.

· Value is the value stored at the offset.

By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.

Example:

   BYTE = 20000, 216

Checksum

Detects the sum of all values stored at a specific set of bytes and compares the sum to a specified value. This attribute requires three entries (separated by a comma and a space):

· Start location is the data offset where the summed values begin (in bytes).

· Length is the total number of bytes that are summed.

· Checksum value is the value checked against the summed values.

By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.

Example:

   Checksum = 10000, 300, 32444

CRC

Detects the sum of all values stored at a specific set of bytes and compares the sum to a specified value. Unlike Checksum, CRC takes into account the sequence of the summed bytes. This makes it a more reliable identification of a file.

This attribute requires three entries (separated by a comma and a space):

· Start location is the data offset where the summed values begin (in bytes).

· Length is the total number of bytes that are summed.

· Checksum value is the value checked against the summed values.

SMS uses the CCITT-CRC standard to evaluate CRC. You must specify a CRC value computed with the CCITT-CRC algorithm.

By default, the entries are decimal. To specify a hexadecimal number, start the hexadecimal number with 0x.

Example:

   CRC = 5000, 300, 38707

Date

The date of the file in decimal format: mm, dd, yy. The entries must be separated by a comma and a space.

Example:

   Date = 9, 2, 93

Size

The size of the file (in bytes).

Example:

   Size = 2766592

Time

The time of the file (using the 24-hour clock) in hours and minutes (hh, mm). The entries must be separated by a comma and a space.

Example:

   Time = 14, 18

LONG

An unsigned LONG value. This attribute requires two entries (separated by a comma and a space):

· Location is the data offset in bytes.

· Value is the value stored at the offset.

Example:

   LONG = 30000, 1346373702

WORD

A WORD value. This attribute requires two entries (separated by a comma and a space):

· Location is the data offset in bytes.

· Value is the value stored at the offset.

Example:

   WORD = 40001, 15488

Token # (1–4)

A string value. This attribute requires two entries (separated by a comma and a space):

· Location is the data offset in bytes.

· Value is the string value stored at the offset. The string value must be enclosed by quotation marks. You can define up to four separate token entries.

Example:

   Token 1 = 710, "WIN"
   Token 2 = 714, "EXCEL"

For information about using PDFs to distribute software, see Chapter 5, "Working with Systems Management Server."


Sample Package Definition File

The following text is from the PDF file for Microsoft Excel for Windows 95 (EXC95.PDF file):

[PDF]
Version=1.0

[Package Definition]
Product=Microsoft Excel 95
Version=7.0
Comment=Microsoft Excel 95
SetupVariations=Compact, Typical, Complete, Custom, Uninstall
WorkstationAccess = UserRead, UserWrite, GuestRead

[Compact Setup]
CommandLine=setup.exe /Q1 /B2
CommandName=Compact
UserInputRequired=FALSE
SupportedPlatforms=Windows95, Windows NT (x86)
SystemTask=FALSE

[Typical Setup]
CommandLine=setup.exe /Q1 /B1
CommandName=Typical
UserInputRequired=FALSE
SupportedPlatforms=Windows95, Windows NT (x86)
SystemTask=FALSE

[Complete Setup]
CommandLine=setup.exe /Q1 /B3
CommandName=Complete
UserInputRequired=FALSE
SupportedPlatforms=Windows95, Windows NT (x86)
SystemTask=FALSE

[Custom Setup]
CommandLine=setup.exe
CommandName=Custom
UserInputRequired=TRUE
SupportedPlatforms=Windows95, Windows NT (x86)
SystemTask=FALSE

[Uninstall Setup]
CommandLine=setup.exe /Q1 /U
CommandName=Uninstall
UserInputRequired=TRUE
SupportedPlatforms=Windows95, Windows NT (x86)
SystemTask=FALSE

[Setup Package for Sharing]
ShareName=exc95sh
ShareAccess=UserRead, GuestRead

[Program Item Properties 1]
CommandLine=excel.exe
Description=Microsoft Excel 95 Install
ConfigurationScript=smsacm32.exe exc95+install setup.stf "SETUP.EXE /B4 /Q1" "SETUP.EXE /U /Q1"
RegistryName=exc95+install
DefaultINIFile=
RunMinimized=FALSE
RunLocalCopyIfPresent=FALSE
DriveMode=UNC
SupportedPlatforms=Windows95
SetupIcon=EXC9501.ICO
DisplayIconInProgGroup=TRUE

[Setup Package for Inventory]
InventoryThisPackage=TRUE
Detection Rule Part 1=File 1
; These lines are comments
; Detection Rule Part 2=AND
; Detection Rule Part 3=File 2

[File 1]
FILE=EXCEL.EXE
COLLECT=FALSE
Checksum=
DATE=7,20,95
SIZE=4828160
TIME=00, 00


Management Information Format Files

The management information format (MIF) is a standard format for describing desktop computer components (hardware and software). The MIF was defined by the Desktop Management Task Force (DMTF). For more information about the MIF, see the Desktop Management Interface Specification version 4.5 (DMI45.DOC) provided on the Microsoft BackOffice Resource Kit compact disc.

A MIF file is a text file that uses the MIF format to describe computer components. SMS uses six types of MIF files to provide information to the SMS database:

  • Personal Computer MIF files (*.MIF)
  • SMSEvent MIF files (*.EMF)
  • UserGroup MIF files (*.UMF)
  • JobDetails MIF files (*.JMF)
  • PackageLocation MIF files (*.PMF)
  • Custom architecture MIF files (*.MIF)

Note

In previous versions of SMS, all MIF files were named with the .MIF file extension. If you have any computers running a previous version of SMS, those computers will continue to report all MIF files with the .MIF file extension.

Using MIF files, you can add objects with custom architectures to the inventory (such as printers and routers), add a new object to an existing architecture, and add groups (such as device driver information, hardware peripherals, and monitors) to computers already existing in the SMS database.


Basic MIF File Keywords

In an SMS site database, the inventory has a hierarchical structure. An architecture is the highest level in the SMS hierarchy, defining the structure for a set of objects. Each object is composed of one or more groups. Each group contains one or more attributes.

This hierarchy is reflected in the MIF file format. The following keywords are used in MIF files to describe computer components:

Architecture

A standard structure for describing a set of related objects in SMS. An architecture is defined by the Architecture group, which specifies a unique architecture name. For example, the Personal Computer architecture has a structure for describing Intel x86, Alpha, MIPS, and Macintosh-based computers.

Object

A specific item within a specific architecture. For example, a specific Macintosh computer (for example, Mac1) can be an object in the Personal Computer architecture. In a MIF file, an object is equivalent to a component block.

For a specific object, the attributes of its Identification group combine to form a unique identifier for the object. The Identification group for Personal Computer objects contains six attributes that are used to uniquely identify a computer.

Group

A structure for defining the distinct parts of an object. A group combines a set of attributes into a single, identifiable entity. For example, Processor, Network, and Operating System are some of the groups that exist on a computer with the Personal Computer architecture.

A group is identified by its class and keyed attributes. For a group class, each attribute's data type and size is set when that attribute is first reported to the SMS database.

In the Personal Computer architecture, groups can be used to store the properties of a hardware device (such as a COM port or mouse), a piece of software (such as the operating system or a defined software package), or any logical entity (such as asset or employee information through custom MIF files).

Attribute

A property of a group. For example, a Disk group on a computer has attributes such as Drive Index, Storage Type, Free Storage, and so on. Each attribute is assigned a value. For example, a Disk Index attribute is assigned a value such as A, B, C, and so on.

Object Syntax

An SMS object is a specific item that uses a specific architecture. For example, the SMS system uses the Personal Computer architecture to inventory computers as objects. An object contains groups. For SMS, an object must have an Identification group and an Architecture group.

An object definition within a MIF file starts with the line Start Component and ends with the line End Component. Within an object definition, you should have the following entry:

Name

A string (enclosed by quotation marks) that labels the object.

Example of an object definition:

Start Component
    Name = "EMPLOYEE"
    Start Group
        Name = "Architecture"
        ID = 1
        Class = "MICROSOFT|ARCHITECTURE|1.0"
        Start Attribute
            Name = "ArchitectureName"
            ID = 1
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(10)
            Value = "Employee"
        End Attribute
    End Group
    Start Group
        Name = "Identification"
        ID = 2
        Class = "MICROSOFT|IDENTIFICATION|1.0"
        Start Attribute
            Name = "Employee Name"
            ID = 1
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(32)
            Value = "Steven Andrew"
        End Attribute
    End Group
End Component

Group Syntax

A group is a set of one or more attributes. When the inventory for an object is displayed in the object's Properties window, all the groups for the object are displayed in the left pane. The attributes for the selected group are displayed in the right pane.

Objects (called Components in the DMTF structure) for every architecture must have an Identification group and an Architecture group.

A group starts with the line Start Group and ends with the line End Group. Within the group, specify the following entries:

Name

A string (enclosed by quotation marks) that labels the group. When the group is displayed in the Properties window, this string is used to label the group in the left pane.

ID

A number that identifies the group. The ID must be unique for each group within the object. The ID is an integer value. Group IDs must be 1 or greater.

Key

Applies only to multiple-instance groups. For example, an object such as a disk drive can have multiple instances on a computer. One or more keys are used to differentiate the instances. For example, the Disk Drive group has a key defined for the Drive Index attribute. The Key entry specifies one or more IDs for the attributes used to uniquely identify an instance of a group. If you have multiple keys, you must separate them with commas. If a group can have only a single instance, then no key should be defined.

Class

A required string describing the source of the group definition.

A group also contains one or more attributes.

Example of a group:

Start Group
    Name = "Employee Name"
    ID = 1
    Class = MICROSOFT|EMPLOYEE NAME|1.0
    Start Attribute
        Name = "Last Name"
        ID = 1
        Access = READ-ONLY
        Storage = SPECIFIC
        Type = String(32)
        Value = "Smith"
    End Attribute
    Start Attribute
        Name = "First Name"
        ID = 2
        Access = READ-ONLY
        Storage = SPECIFIC
        Type = String(32)
        Value = "John"
    End Attribute
End Group
Identification Group Syntax

Objects for every architecture must have an Identification group. The Identification group can have any number of attributes. However, you should ensure that all attributes are included in all objects that are part of a single custom architecture.

Start Group
    Name = "Identification"
    ID = 1
    Class = "MICROSOFT|IDENTIFICATION|1.0"
    Start Attribute
        Name = "Employee Name"
        ID = 1
        Access = READ-ONLY
        Storage = SPECIFIC
        Type = String(32)
        Value = "Mitch Duncan"
    End Attribute
End Group
Architecture Group Syntax

Objects for every architecture must also have an Architecture group. The Architecture group contains one attribute. The value of the ArchitectureName attribute should be the label you want to display for the architecture in the SMS Administrator. For example, when you view an object with a custom architecture named EMPLOYEE, the ArchitectureName attribute value EMPLOYEE is displayed in the Properties window title bar.

Start Group
    Name = "Architecture"
    ID = 1
    Class = "MICROSOFT|ARCHITECTURE|1.0"
    Start Attribute
        Name = "ArchitectureName"
        ID = 0
        Access = READ-ONLY
        Storage = SPECIFIC
        Type = String(10)
        Value = "Employee"
    End Attribute
End Group

Attribute Syntax

When the inventory for an object is displayed in the object's Properties window, all the groups for the object are displayed in the left pane. The attributes for the selected group are displayed in the right pane.

An attribute starts with the line Start Attribute and ends with the line End Attribute. Within the attribute, you should have the following entries:

Name

A string (enclosed by quotation marks) that labels the attribute. When the attribute is displayed in the Properties window, this string is used to label the attribute in the right pane.

ID

A number that identifies the attribute. The ID must be unique for each attribute within the group. The ID is an integer value.

Access

Determines the access type of the table where the attribute will be stored. Values can be READ-ONLY, READ-WRITE and WRITE-ONLY. The Access statement is optional and defaults to READ-ONLY.

Storage

Assists management applications to optimize storage requirements. Values can be common or specific. Common attributes are for properties that are likely to be common among many on most computers (for example, the processor name should be a common attribute). Specific attributes are for properties that are likely to have unique values on most computers (for example, the amount of free disk space should be a specific attribute). The Storage statement is optional.

Type

The data type used to store the value of the attribute. There are two data types. Counter is an integer. String is a character string. For strings you must specify the maximum length for the string.

The SQL Server database has a limit of 255 characters for any attribute value. Any string longer than 255 characters will be truncated. In addition, any values longer than the originally defined length will be silently truncated. For example, if attribute Employee Name is defined as string(40), SMS will add only the first 40 characters for an Employee Name value that is longer than 40 characters.

The SMS system uses the first definition of type. For example, if you first defined Employee Name as string(40), the SMS system will always use that type. You cannot change the Type after you have first defined it.

Value

The value assigned to the attribute. The value must be in the form specified by Type. Strings must be enclosed within quotation marks. Counters must be decimal integers. The Value statement is optional.

Example of an attribute definition:

Start Attribute
    Name = "Hours Worked"
    ID = 1
    Access = READ-ONLY
    Storage = SPECIFIC
    Type = Counter
    Value = 500
End Attribute


Differences Between SMS and the DMI 4.5 MIF Specification

In general, the SMS system can use any MIF file that complies with version 4.5 of the Desktop Management Interface (DMI) specification. However, SMS treats some aspects of the MIF syntax in a way that is unique to SMS. In addition, although the full DMI 4.5 syntax is accepted by the SMS MIF parser, some fields are not used. The following sections outline the differences between SMS and DMI MIF files:

ComponentID group is supported but not enforced.

DMI 4.5 requires this group; however, the SMS MIF parser does not enforce this requirement. The ComponentID group is checked for correct syntax only. If the group does not exist in the MIF file, the parser will not report an error.

Some data types are simplified or merged.

DMI 4.5 has numerous data types: five types of integers, three types of strings, and one date type. SMS handles these data types in the following manner:

  • All integer types (int, integer, int64, integer64, gauge, counter, and counter64) are treated as signed 32-bit values. Therefore, values exceeding 32 bits will not be correctly evaluated. Likewise, 32-bit unsigned values above 0x7FFFFFFF will be variously interpreted as unsigned 32-bit values or signed 32-bit values, depending on the context. However, the MIF parser will forward these values to other components as signed 32-bit integers.
  • All string types (displaystring, string, octetstring) are treated as the same type for database purposes. Because SQL Server places a limit of 255 characters on strings, any strings longer than 255 characters in the MIF file will be truncated. However, there is no string length limitation in the syntax itself for attribute values. Strings should not exceed 255 characters in length, and they should not contain embedded NULL characters via an escape sequence.
  • Enumeration types are evaluated as the symbolic string and not as the integral value represented by the enumeration string. The enumeration string is preserved as a database item. Enumeration types take on the string type when the MIF file has been parsed and evaluated. Enumeration types may be specified by using either the integer symbol or the enumeration string itself in all contexts where an attribute value is required.

Unicode MIF files are detected but not supported.

DMI 4.5 allows Unicode MIF files. The SMS Inventory Processor will not process a Unicode MIF file, and will report an error. The MIFCHECK utility will report that Unicode MIF files are not supported.

The Language statement is parsed but not used.

DMI 4.5 allows a Language statement that describes the language of the MIF file. SMS parses the Language statement but does not use it for any purpose.

PRAGMA is a keyword for SMS.

DMI 4.5 does not specify PRAGMA as a keyword. SMS uses the PRAGMA keyword to send commands between components. The PRAGMA statement can be used in a MIF group definition. The PRAGMA statement specifies a string that contains a command. The PRAGMA string is case-insensitive. If no PRAGMA is specified, the command is Add by default.

SMS supports three pragma types:

· Pragma SMS:Add adds the group to the computer's inventory in the database.

· Pragma SMS:Update updates the group in the database with the information in the Delta-MIF file.

· Pragma SMS:Delete removes the group from the computer's inventory in the database. Deleting the Identification group removes all records for the computer from the database.

Description statements are not used in SMS.

With DMI 4.5, you can use a Description statement to describe a component, group, or attribute. SMS parses Description statements but does not use them for any purpose.

The class string is converted to uppercase but not checked for internal format.

The class string is converted to uppercase, but not checked for internal format, because this is not a strict requirement in the specification. The conversion to uppercase is done to force all subsequent users of the CLASS string to treat it in a case-insensitive manner. Rather than relying on other components to do this, the parser converts the string to uppercase.

Path definitions are parsed but not used.

With DMI 4.5, you can use a Path statement to locate component instrumentation files. SMS parses Path statements but does not use them for any purpose.

Attributes that use Instrumentation Symbolic Names are parsed but not used.

With DMI 4.5, you can use a Path statement to specify Instrumentation Symbolic Names to specify paths to libraries that contain the actual value of an attribute. SMS parses attributes that use Instrumentation Symbolic Names but does not use them for any purpose.

The Unsupported keyword forces an attribute to be ignored in the SMS system.

With DMI 4.5, you can specify the keyword Unsupported to tell the DMI service layer that an attribute is not supported by a component.

For SMS, an Unsupported keyword applied to an attribute value causes that attribute to be specially marked. The MIF parser will retain the Unsupported tag; however, the Inventory Processor will ignore such attributes, treating them as though they were not present in the MIF file.

The Access statement is parsed but not used.

DMI 4.5 lets you use an Access statement to specify the access to an attribute. SMS parses Access statements but does not use them for any purpose. The Access statements have meaning only to the DMI service layer. However, the restrictions in the DMI specification on the correct or incorrect placement of these values with regard to enumerated types or key values are still enforced.

There are several restrictions on the Date data type.

The Date data type has the following restrictions:

· The value for an attribute with the Date data type must be represented using the full 25 octets required for the Date data type. You should pad values with zeroes if necessary (for example, the month of May should be represented as 05, not 5). If a date field has no value, you should place zeroes in that field.

· The microsecond field is ignored. SMS will store dates only to the resolution of one second. However, you must still specify zeros in the microsecond field.

· The UTC offset is parsed and available for use by SMS components, but currently no SMS components use the UTC offset information.

· An attribute cannot contain a date before 1980 or after 2030. Date attributes outside of this range will be considered errors by the SMS MIF parser.

· The asterisk character (*) in a date field is replaced with the value for the current date in the corresponding field on the computer where the MIF parser is running.

With DMI 4.5, you can use asterisks to avoid specifying a part of a date. SMS requires that a date value be a complete date value because SQL Server cannot store partial date values. An attribute that contains all asterisks will be considered a NULL or blank date in the SMS database.

For example, if the current date is November 11, 1995, the value 1995**01130000.000000+000 would be processed as 1:00 P.M., November 1, 1995 (** is replaced by 11, the current month).

· For non-English versions of SMS, the MIF syntax and keywords must be in English, but the string data can be in the localized language of the client.

For the String data type, you should use escape characters for characters outside the standard ANSI range (32 through 127).

Literal (non-escape) characters embedded in quoted strings outside of the range 32 to 127 will be parsed and passed on to the rest of the system. These values may have different appearances, depending upon the active display font. Strictly speaking, for string types, you should restrict the characters to the ISO 8859-1 character set. However, the parser does not currently enforce this particular character set.

All escape characters are fully interpreted as the correct 8-bit value. You should be careful when using escape characters. For example, a NULL in the middle of a string "abc\0abc" causes SMS to interpret the string as having a length of only three characters. Although the parser supports a stream of bytes by this mechanism, SMS truncates the string when it detects an escape NULL.

Also note that how the escape character is stored in the SMS database depends on the character set used by the SQL Server containing the database. How the escape character is displayed depends on the code page used by the computer running the SMS Administrator.

For the String data type, you should explicitly declare the string length, which must be 255 characters or less.

DMI 4.5 does not require you to specify the string length of an attribute with a String data type, and it does not impose limits on the string length. However, for SMS you should explicitly declare the length of all String data types, and you should limit the string length to 255 characters or less.

Because of the 255-character limit for SQL Server, the Inventory Processor does not support string lengths longer than 255 characters. Any string that is longer than 255 characters will be truncated to the first 255 characters. The SMS MIF parser will not report an error if the declared string length exceeds 255 characters.

If an attribute with a String data type does not have a declared string length, SMS will use the string length of the value that is specified for the first occurrence of the attribute. This string length will be used as the declared string length of the attribute. Any attributes of the same type will use the declared string length as the string length of the attribute.

For Groups and Tables, the SMS MIF parser does not enforce the uniqueness of key attributes.

DMI 4.5 requires that the key attributes be unique. You should follow the DMI recommendations. If a key attribute is not unique, SMS will store only the last instance of the duplicated key attribute.


Checking MIF Files

You can check the syntax of a MIF file using the MIFCHECK utility. The MIFCHECK utility runs the same MIF parser used by the SMS components. Therefore, any MIF file accepted by MIFCHECK will also be accepted by the SMS system. MIFCHECK verifies that the specified MIF files adhere to the syntax of the DMI Specification version 4.5 with the exceptions noted in the preceding section.

The MIFCHECK utility is provided on the Microsoft BackOffice Resource Kit compact disc. See the SMSTOOLS.HLP file on the compact disc for more information.


Predefined Architecture MIF Files

There are six architectures predefined in the SMS database. These architectures are:

  • Personal Computer
  • SMSEvent
  • UserGroups
  • JobDetails
  • PackageLocation
  • SNMP Traps

You can use MIF files to add information about five of these six architectures to the SMS database (you cannot use MIF files to add information about SNMP traps). These MIF files can vary in size, but in general they are too large to include examples for all types in this manual. You can view samples of each of these MIF files on an SMS site server in the SITE.SRV\DELTAMIF.COL\PROCESS directory.


Package Command Status MIF File

When Package Command Manager runs a package command on an SMS client, the package command can write a detailed status MIF file to the Windows directory. This status MIF file is called a package command status MIF file. This file is processed by the Despooler and is used to create a job status MIF file (*.JMF). For more information about how these files are processed, see "How Package Command Status MIF Files Are Processed" in Chapter 3.

This is a template for a package command status MIF file. Items in italics are variables that must be replaced.

START COMPONENT
  NAME = "WORKSTATION"
  START GROUP
    NAME = "ComponentID"
    ID = 1
    CLASS = "DMTF|ComponentID|1.0"
    START ATTRIBUTE
      NAME = "Manufacturer"
      ID = 1
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING (string length up to 255)
      VALUE = "Manufacturer"
    END ATTRIBUTE
    START ATTRIBUTE
      NAME = "Product"
      ID = 2
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Product"
    END ATTRIBUTE
    START ATTRIBUTE
      NAME = "Version"
      ID = 3
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Version"
    END ATTRIBUTE
    START ATTRIBUTE
      NAME = "Serial Number"
      ID = 4
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Serial Number"
    END ATTRIBUTE
    START ATTRIBUTE
      NAME = "Installation"
      ID = 5
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Date Time"
    END ATTRIBUTE
  END GROUP
  START GROUP
    NAME = "InstallStatus"
    ID = 2
    CLASS = "MICROSOFT|JOBSTATUS|1.0"
    START ATTRIBUTE
      NAME = "Status"
      ID = 1
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Success" or "Failed"
    END ATTRIBUTE
    START ATTRIBUTE
      NAME = "Description"
      ID = 2
      ACCESS = READ-ONLY
      STORAGE = SPECIFIC
      TYPE = STRING(string length up to 255)
      VALUE = "Error Message"
    END ATTRIBUTE
  END GROUP
END COMPONENT


Custom Architecture MIF Files

When you add a new type of object to the SMS database, the MIF file containing the object's inventory must have an Architecture group and an Identification group. This type of MIF file is called an IDMIF.

When you add a new group to an existing object, the MIF file containing the group(s) must not have an Architecture group or an Identification group. This type of MIF file is called a NOIDMIF.

When creating a MIF file to add or update an object with a custom architecture, observe the following rules:

  • The full definition for the object starts with the keyword Start Component and ends with End Component. You should define only one object (component) per MIF file.
  • The object definition begins with the Name entry for the object.
  • The Identification and Architecture groups must be included in the MIF file, using the structure you defined for the architecture.
  • The Class value for the Identification group should be:

    MICROSOFT|IDENTIFICATION|1.0.
  • The Class value for the Architecture group should be:

    MICROSOFT|ARCHITECTURE|1.0.
  • If you want the object to appear in the Sites window of the SMS Administrator, you must include the Name, Site, Domain, SystemRole, and SystemType attributes in the Identification group; and the values for the Site and Domain attributes must be those of sites and SMS domains existing in the SMS database. If a custom architecture does not have these attributes defined, its objects are not displayed in the Sites window; you must display these objects by using a query.
  • The group and attribute ID values must be 1 or greater.
  • The attributes for an object must be specified in groups that adhere to the structure you defined for the architecture.

Important

When updating inventory information for an object already existing in the SMS database, make sure to specify values for all of the attributes defined in the previous MIF file for that object; otherwise the values for those attributes will be set to NULL.

Sample Custom Architecture MIF File

The following MIF file adds an object with a custom architecture called "Employee" to the SMS database. The group types are Identification, Architecture, Employee Status, Location, and Position.

Start Component
    Name = "EMPLOYEE"
    Start Group
        Name = "Identification"
        ID = 1
        Class = "MICROSOFT|IDENTIFICATION|1.0"
        Start Attribute
            Name = "Site"
            ID = 1
            Access = READ-ONLY
            Storage = COMMON
            Type = String(3)
            Value = "PIT"
        End Attribute
        Start Attribute
            Name = "Domain"
            ID = 2
            Access = READ-ONLY
            Storage = COMMON
            Type = String(15)
            Value = "SHUPPDOM"
        End Attribute
        Start Attribute
            Name = "SystemType"
            ID = 3
            Access = READ-ONLY
            Storage = COMMON
            Type = String(50)
            Value = "Person"
        End Attribute
        Start Attribute
            Name = "SystemRole"
            ID = 4
            Access = READ-ONLY
            Storage = COMMON
            Type = String(50)
            Value = "Writer"
        End Attribute
        Start Attribute
            Name = "Name"
            ID = 5
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(64)
            Value = "Ben Cole"
        End Attribute
        Start Attribute
            Name = "Project"
            ID = 6
            Access = READ-ONLY
            Storage = COMMON
            Type = String(32)
            Value = "SMS"
        End Attribute
        Start Attribute
            Name = "Company"
            ID = 7
            Access = READ-ONLY
            Storage = COMMON
            Type = String(32)
            Value = "Siblings Inc"
        End Attribute
    End Group
    Start Group
        Name = "Architecture"
        ID = 2
        Class = "MICROSOFT|ARCHITECTURE|1.0"
        Start Attribute
            Name = "ArchitectureName"
            ID = 1
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(10)
            Value = "Employee"
        End Attribute
    End Group
    Start Group
        Name = "Employee Status"
        ID = 3
        Class = "MICROSOFT|EMPLOYEE STATUS|1.0"
        Start Attribute
            Name = "Hours Worked"
            ID = 1
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = Counter
            Value = 500
        End Attribute
        Start Attribute
            Name = "Done?"
            ID = 2
            Access = READ-ONLY
            Storage = COMMON
            Type = String(40)
            Value = "No"
        End Attribute
    End Group
    Start Group
        Name = "Location"
        ID = 4
        Class = "MICROSOFT|LOCATION|1.0"
        Start Attribute
            Name = "Building"
            ID = 1
            Access = READ-ONLY
            Storage = COMMON
            Type = String(40)
            Value = "1"
        End Attribute
        Start Attribute
            Name = "Office Number"
            ID = 2
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(40)
            Value = "222"
        End Attribute
        Start Attribute
            Name = "Phone"
            ID = 3
            Access = READ-ONLY
            Storage = SPECIFIC
            Type = String(40)
            Value = "M"
        End Attribute
    End Group
    Start Group
        Name = "Position"
        ID = 5
        Class = "MICROSOFT|POSITION|1.0"
        Start Attribute
            Name = "Title"
            ID = 1
            Access = READ-ONLY
            Storage = COMMON
            Type = String(40)
            Value = "Technical Writer"
        End Attribute
        Start Attribute
            Name = "Level"
            ID = 2
            Access = READ-ONLY
            Storage = COMMON
            Type = Integer
            Value = 2
        End Attribute
    End Group
End Component


SNMP Export Files

The SMS Event to Trap Translator allows you to export trap configurations that you have defined in the SMS Administrator. You can export definitions in two formats: the configuration tool (CNF) format, and the trap text (TXT) format. The CNF format is used to export configurations that can be used with the Event Configuration tool to configure the Event to Trap Translator on computers running Windows NT. The TXT format is used to export configurations that can then be imported into other SNMP systems.

These file formats are described in the following sections.


SNMP Configuration Tool Format Files

The configuration tool included with SMS is used to modify the configuration of the Event to Trap Translator through an SMS job. It allows the user to provide a data file that creates, deletes, and modifies the configuration of translated events. The tool can also be used to modify trap destinations and communities.

The tool generates an SMS status MIF file after it runs to indicate the overall status of the operation. It also generates a text log file with detailed information on which statements succeeded or failed. If any particular line results in an error, an error is written to a log file and processing continues with the next line in the file.

This tool is called EVENTCMx.EXE, where x is I for Intel, A for Alpha, and M for MIPS. This tool is located in the MSTEST directory on all SMS logon servers.

The syntax for adding or deleting events using the configuration tool format is:

#pragma {add | delete} eventlog eventsource eventID [count=#] [time=#]

add

Adds the specified event to the list of events to be translated to traps. If there are any errors in the add parameters, the event is not added and an error is returned. If the specified event and event source are already configured, then the count and time values are modified.

delete

Deletes the specified event from the translation list. If the event specified is not in the configuration, an error is returned.

eventlog

The Windows NT event log that contains the event. There are three possible values for this entry: System, Application, and Security.

eventsource

The source specified in the Windows NT event log. If the event source is more than one word, it should be enclosed in quotation marks.

eventID

The 32-bit event identification number. This is partially based on the 16-bit event number specified in the Windows NT event log.

count

The number of times that the event must occur before generating a trap. For example, you can specify that the event must occur 5 times before it is translated.

time

The time period for the count. For instance, you can specify that the event must occur 5 times in an hour to be translated.

The syntax for modifying SNMP trap destinations is:

#pragma {add_trap_dest | delete_trap_dest} community address

add_trap_dest

Adds the specified address to the list of trap destinations for the specified community. If the community does not exist, it is created and the address is added. If the specified address already exists in the specified community, the statement is ignored.

delete_trap_dest

Deletes the specified address from the specified community. If the community does not exist or the address is not in the community, an error is written to the log.

community

The group of computers to which the pragma should be applied.

address

The trap destination TCP/IP address.

A semicolon in the first column of any line indicates a comment line. A sample CNF file follows:

; this is a sample CNF file
;
; the next line configures Rdr event 8003
#pragma Add System "Rdr" 3221227472 1 0
;
; the next line sets up the trap destination address
#pragma Add_Trap_Dest public 198.255.255.255
; end of file


Trap Text Format Files

The trap text format is designed to allow a user at an SNMP console to import the configuration of traps into their SNMP console. The format is a comma separated list of the information about the defined traps. The fields in the trap text format are as follows:

Enterprise OID (enterprise object identifier)

A series of numbers that uniquely identifies the trap source.

Source Name

The name of the event source, specified in quotes.

6

A literal number six, indicating that the trap is a specific trap.

Specific ID

The 32-bit specific trap identification number.

Number of VARBinds (variable bindings)

The number of VARBinds specified by the trap. VARBinds are lists of variable elements describing the trap. All traps include at least five VARBinds in addition to the VARBinds specified in the format string.

Format string from DLL

The format string specified for the trap. Any non-printing characters in the format string (such as carriage returns, line feeds, and tabs) must be converted to their escape equivalents.

All of the data for a given event is put on a single line in the text file with no line breaks. A sample exported trap text file line follows:

.1.3.6.1.4.1.311.1.4.1.2.65.66, "AB", 6, 1073741824, 8, "The object called %1%n was %t%2 and %t%3."

The number of VARBinds in this example is eight: the five VARBinds that are included in all traps, and the three additional VARBinds for the three substitution strings in the event.


Client Configuration Request Files

The client configuration request (CCR) notifies the Client Configuration Manager that a particular Windows NT-based client needs to be configured. The CCR file is a small text file with an INI file format. The file is named SMSID.CCR, where SMSID is the 8 character SMS ID assigned to the client.

New CCR files are created by SMS Client Setup for Windows NT (CLI_NT). CCR files are placed in the LOGON.SRV\CCR.BOX directory. CCR files that have failed at least one processing attempt by Client Configuration Manager are moved to the LOGON.SRV\CCR.BOX\RETRY directory.

The CCR file has two sections:

  • [NT Client Configuration Request]
  • [Request Processing]

Dates and times in the [NT Client Configuration Request] section are relative to the client. The [NT Client Configuration Request] section has the following keys:

Machine Name

The name of the target client. It is used by Client Configuration Manager to locate the computer.

Domain

The name of the SMS domain that the client belongs to, as determined by CLI_NT. Client Configuration Manager uses this field to establish remote administrative access to the system.

Initial Request Date

The date and time when CLI_NT created a new CCR.

Latest Request Date

The date and time that CLI_NT last updated the CCR.

Client Request Count

The number of times that CLI_NT requested configuration work since this CCR was created.

Dates and times in the [Request Processing] section are relative to the server running Client Configuration Manager. The [Request Processing] section has the following keys:

Initial Processing Attempt

The date and time when Client Configuration Manager first attempted to process the request. It is used to determine when to report a delayed error event to the SMS database.

Retry Interval Start

The date and time when Client Configuration Manager first attempted to process the request after a new CCR was received for this computer. It is used to determine when to stop retrying this request and report an event to the SMS database.

Latest Processing Attempt

The date and time when Client Configuration Manager last attempted to process the request.

Number of Processing Attempts

A count incremented each time Client Configuration Manager unsuccessfully attempts to process the request.

Last Error Code

A numeric code indicating the error that prevented Client Configuration Manager from processing the request on the latest attempt.

The keys Machine Name, Domain, Initial Request Date, Latest Request Date, and Client Request Count are written by CLI_NT when the request is created.

The keys Latest Request Date, Client Request Count, and Retry Interval Start are updated by Client Configuration Manager when it finds that a CCR already exists for the specified SMS ID.

The keys Initial Processing Attempt, Latest Processing Attempt, Number of Processing Attempts, and Last Error Code are updated each time Client Configuration Manager encounters an error while attempting to process the CCR.

A sample CCR file follows:

[NT Client Configuration Request]
Machine Name=MACHINE01
Domain=SMS_DOMAIN
Initial Request Date=01/01/1996 23:00
Latest Request Date=01/01/1996 23:00
Client Request Count=1

[Request Processing]
Initial Processing Attempt=01/01/1996 23:14
Retry Interval Start=01/01/1996 23:14
Latest Processing Attempt=01/04/1996 3:44
Number of Processing Attempts=8
Last Error Code=5


Chapter 5 - Working with Systems Management Server

This chapter describes how to work with the following Microsoft Systems Management Server (SMS) components:

  • Package definition files
  • Network Monitor
  • Remote Control
  • SNMP traps

For overview information about these topics, refer to the SMS version 1.2 Administrator's Guide.


Working with Package Definition Files

A package definition file (PDF) is an ASCII file that contains predefined Workstations, Sharing, and Inventory property settings for a package. When you create a new package, you can use a PDF to specify the properties for the package.

Note

When you create a PDF, be sure to include an icon file (.ICO) for the application if it will use Program Group Control, in the SetupIcon entry. (You cannot specify other types of files, such as .EXE, in this entry.)


Using PDFs with SMS Jobs

SMS uses jobs to distribute packages to target systems. There are three primary types of jobs for this purpose: Run Command on Workstation, Share Package on Server, and Remove Package From Server.

There are various job options that you can specify, depending on the type of job that you are creating. The main options that affect distribution software are the specification of targets, the distribution servers where the package will be made available, and the options for the Run Phase.

The most flexible mechanism for specifying job targets is an SMS database query. You can create a query that allows you to target only those clients or servers that meet the criteria for the particular package that you are going to install. Once you have defined and run the query, the resulting set of clients or servers can be specified as the target of the job.

Run Command On Workstation Jobs

Run Command On Workstation jobs are the most common type of job used in SMS. This job is actually run on the target clients in the context of the package share that is associated with the job. It is used to install, remove, and maintain software on target clients.

The following is a sample of a PDF that might be included in a Run Command On Workstation job:

[PDF]
Version=1.0

[Simple Server Install Setup]
CommandLine=instsrv.bat Install
CommandName=Automated installation of the Simple Service
UserInputRequired=FALSE
SynchronousSystemExitRequired=FALSE
   SupportedPlatforms = Windows NT 3.5 (Alpha), Windows NT 3.5 (MIPS), Windows NT 3.5 (x86), Windows NT 3.51 (Alpha), Windows NT 3.51 (MIPS), Windows NT 3.51 (x86), Windows NT 4.0 (Alpha), Windows NT 4.0 (MIPS), Windows NT 4.0 (x86)

[Simple Server Uninstall Setup]
CommandLine=instsrv.bat Remove
CommandName=Automated deinstallation of the Simple Service
UserInputRequired=FALSE
SynchronousSystemExitRequired=FALSE
SupportedPlatforms = Windows NT 3.5 (Alpha), Windows NT 3.5 (MIPS), Windows NT 3.5 (x86), Windows NT 3.51 (Alpha), Windows NT 3.51 (MIPS), Windows NT 3.51 (x86), Windows NT 4.0 (Alpha), Windows NT 4.0 (MIPS), Windows NT 4.0 (x86)

[Package Definition]
Product=Simple Server
Version=1.0
Comment=Simple Server from the WIN32 samples of VC++ 2.0
SetupVariations=Simple Server Install, Simple Server Uninstall

[Setup Package for Inventory]
InventoryThisPackage=TRUE
Detection Rule Part 1=file 1

[file 1]
FILE=SIMPLE.EXE
COLLECT=FALSE
Checksum=
CRC=
DATE=
SIZE=
TIME=
BYTE=
WORD=
LONG=
TOKEN 1=
TOKEN 2=
TOKEN 3=
TOKEN 4=

Share Package On Server Jobs

The Share Package On Server job is used to install an SMS network application on a set of servers. Unlike the Run Command On Workstation job, the Share Package On Server job does not actually run a command on the distribution servers. It simply copies the files and directory structure in the package directory to the specified servers and makes them available as a share. The access permissions for each package can be set in the PDF for that package.

The following is an example of a PDF that might be included in a Share Package On Server job:

[PDF]
Version=1.0

[Package Definition]
Product=My Application
Version=1.0
Comment=Sample package for use with Share Package On Server jobs.

[Setup Package for Sharing]
ShareName=MYAPPSHR
ShareAccess=UserRead, GuestRead

[Program Item Properties 1]
Description=My Application
CommandLine=MYAPP.EXE
ConfigurationScript=
RegistryName=MyApp
DefaultINIFile=MYAPP.INI
RunMinimized=TRUE
RunLocalCopyIfPresent=TRUE
DriveMode=UNC
SupportedPlatforms=Windows 3.1
DisplayIconInProgGroup=TRUE
SetupIcon=MYAPP.ICO

Remove Package From Server Jobs

Remove Package From Server jobs do not remove packages from clients; that is done with a Run Command on Workstation job. The Remove Package From Server job is used to remove packages from SMS site servers, distribution servers, and servers that have had a package installed using a Share Package on Server job.

There is no specific PDF for this type of job. Any package in SMS can be the basis for a Remove Package From Server job.


Working with SMS Network Applications

SMS provides fault tolerance and load-leveling for SMS network applications by placing application packages on multiple distribution servers and by choosing, at run time, an available server to service a client.

SMS uses a device driver mechanism for Windows 95 clients to choose application servers. This mechanism is completely transparent to both installation and execution of an application. This device driver mechanism depends upon UNC identification of servers. Any references to servers that an application records in the registry, in INI files, in Start menu shortcuts, or program item command lines, must be UNC paths; drive letters are not supported. Any persistent reference to a server location should contain the UNC from which the setup program was activated. At run time, SMS may translate that UNC into an equivalent UNC which represents the same application on a different server.

An application's PDF file should declare a single setup program item to represent a shared SMS network application. The following sample is extracted from the Office for Windows 95 standard PDF file:

[Program Item Properties 1]
CommandLine=dummy.exe
Description=Microsoft Office95a Std Install
ConfigurationScript=smsacm32.exe ofs95a+install setup.stf "SETUP.EXE /B4 /Q1" "SETUP.EXE /U /Q1"
RegistryName=ofs95a+install
DefaultINIFile=
RunMinimized=FALSE
RunLocalCopyIfPresent=FALSE
DriveMode=UNC
SupportedPlatforms=Windows95, Windows NT 3.1 (x86)
SetupIcon=OFS95A01.ICO
DisplayIconInProgGroup=TRUE

The entries in the application's PDF file should be as follows:

CommandLine

For reasons of backward compatibility, this entry cannot be blank so it should contain some text.

Description

The Start menu shortcut identifier or program item identifier; this entry must not be blank.

ConfigurationScript

Contains the setup program's command line, or, if special preprocessing is desired, the command line of an encapsulation program.

RegistryName

Must be unique to the application and its version.

SupportedPlatforms

See the SMS version 1.2 product documentation for allowable values for this entry.

SetupIcon

Contains the file name of the icon used to represent the setup program. Both the PDF file and the icon file should reside in a package's root directory. This entry is required for Program Group Control, and it only support icon files (.ICO).

The other entries must posses the values indicated in the sample.

You install an SMS network application exactly as you would in the absence of SMS; no changes are made by SMS to Start menu items, program items, registry entries, or INI file entries.

To enable SMS to automatically remove an application upon your request, a setup program or its encapsulation program must record a removal command line in the HKEY_CLASSES_ROOT\SMS\Applications\regname\Info\Deinstall_App registry key. This must specify a full path to the removal program, including the server and share name.

To enable an encapsulation program to determine the UNC path from which a setup program is initiated, SMS records the installation server's UNC path in the HKEY_CLASSES_ROOT\SMS\Applications\regname\InstallationServer registry key. An encapsulation program can then prefix the removal command line with this UNC before recording it into the registry. The regname component is the name for the program item that was entered into the RegistryName entry within the PDF file.


Creating Setup Command Lines for PDFs

The EXECUTE.EXE program, included in this Resource Kit, is used to run a two-phase setup program under the Package Command Manager or Program Group Control configuration script. A two-phase setup is one that is actually two different programs; the first program starts the second one and then terminates. When the first program terminates, Package Command Manager closes the network connection to the distribution server, leaving the second program without a network connection. EXECUTE.EXE delays Package Command Manager (and Program Group Control) from deleting the distribution server connection too soon.

EXECUTE.EXE runs the command line for a Windows-based program and then polls for its termination. Upon termination, it temporarily pauses and waits until no window possessing a given window title or window class can be found.

EXECUTE.EXE can be used for 16-bit applications running under Windows version 3.1, Windows NT or Windows 95. Use this syntax:

execute "command-line" "window-caption" "window-classname"

Where command-line is the command line that your setup program will run, window-caption is the window title, and window-classname is the window class. (Use the SPY.EXE program, distributed with Microsoft Visual C++®, to determine the window class and title.)

The quotation marks around each option are required syntax. The "window-caption" and "window-classname" options can be empty ("").

For example:

execute "SETUP.EXE /B4" "Microsoft PowerPoint" "PPApplicationClass"

execute "SETUP.EXE /B4" "" "PPApplicationClass"

The EXECUTE.EXE program must reside either in the root directory of the package share, or in the MSTEST directory on the SMS logon server (LOGON.SRV\MSTEST).


Deploying Microsoft Exchange with SMS

The Microsoft Exchange PDF allows you to deploy Microsoft Exchange to clients running Windows 95 and Windows NT on your network, using SMS.

Before you can use the Microsoft Exchange PDF, you must:

  • Create the package source directories
  • Pre-set various profile defaults such as E-mail name, Microsoft Exchange Home Server, and Personal Address Book (PAB) location.

To set up package source directories for Microsoft Exchange

1. Create two directories on your source server: one for Windows NT-based clients and the other for Windows 95 clients.

In most cases, these directories are located on your SMS server. Once created, they become your package source directories. Use these directory names: EXCHWINNTxxx and EXCHWIN95xxx, where xxx denotes the language, such as USA, GER or FRN.

2. Share the directories with the same names, for example:

\\servername\EXCHWIN95USA

3. Copy the Microsoft Exchange files into the relevant shares.

This uses approximately 8 – 9 MB of disk space.

To customize the default profile settings for Microsoft Exchange

1. From a package source directory, start STFEDTR.EXE.

The Microsoft Exchange Setup Editor window appears.

2. From the File menu, choose Select Client Installation Point.

The Select Client Installation Directory dialog box appears.

3. Select an Exchange installation point and choose OK.

4. From the File menu, choose Set User Options.

The User Options dialog box appears.

5. Select the Home Server tab.

6. In the Home Server box, type the name of a server in your site where Directory Services are replicated.

When the user first logs on, the Microsoft Exchange Client computer will query the directory to determine which server to connect to in the future.

7. Choose OK to return to the Microsoft Exchange Setup Editor window.

8. From the File menu, choose Save, and then choose Exit.

Creating the SMS Package

Software is distributed through an SMS package. Before distribution can occur, the package must be created. Since Microsoft Exchange provides a set of PDF files, you don't need to create a package manually. For more information, see your Microsoft Exchange documentation.

To create a Microsoft Exchange package

1. In the SMS Administrator, open the Packages window, and from the File menu, choose New.

The Package Properties dialog box appears.

2. Choose Import.

The File Browser dialog box appears.

3. Locate the Microsoft Exchange PDF and choose OK.

The Package Properties dialog box reappears.

4. Choose Workstations.

The Setup Package for Workstations dialog box appears.

5. In the Source Directory box, type the path to the package source directory.

6. In the Workstation Command Lines box, select the type of installation to view.

The Command Line Properties dialog box appears.

7. Make any necessary changes, then choose OK.

Note

If you are creating a Microsoft Exchange package that will use a language other than English, modify the Workstation Command Lines (in the Setup Package for Workstations dialog box, choose Properties). Each language uses different file names for the installation program, for example, French and Swedish use the file name INSTALL.EXE, whereas Spanish uses INSTALER.EXE.

Setting Access Permissions

Setting access permissions allows you to specify user and guest rights to your SMS package directory.

To set access permissions for the Microsoft Exchange package

1. In the Setup Package for Workstations dialog box for the Microsoft Exchange package, choose Access.

The Access dialog box appears.

2. Under Users and Guests, select the Read and Write check boxes.

3. Choose OK.

4. Choose Close.

Sending the Microsoft Exchange Package to a Site

A distribution server is created on your primary site so you can distribute jobs through the SMS package directory.

To send the Microsoft Exchange package to a site

1. In the SMS Administrator, open the Packages window and the Sites window.

2. Drag the Microsoft Exchange package from the Packages window to the site in the Sites window.

The Job Details dialog box appears.

In the Job Details dialog box, confirm the following:

  • The correct package, job destination, and SMS site are selected. If you have subsites, please read about creating multiple sites in the SMS version 1.2 Installation and Configuration.
  • The Distribute Phase check boxes are selected and the correct distribution servers are selected.
  • The Run Workstation Command check box is cleared. This ensures that the package is sent only to the distribution server.

3. Choose OK.

4. Choose Schedule.

The Job Schedule dialog box appears.

5. Choose OK.

6. Choose OK to start the job.

Setting Up User Names for Clients Running Windows NT

To set up user names

1. In the Microsoft Exchange program group, choose the MS Exchange Services icon.

The Default Exchange Profile Properties dialog box appears.

2. Choose Properties.

The Microsoft Exchange Server dialog box appears.

3. Select the General tab.

4. In Mailbox, type the user's e-mail name.

5. Choose Check Name.

6. When the account appears in Mailbox, choose Apply.

Choose OK in all open dialog boxes.


Deploying Windows 95 with SMS

Before you deploy the Windows 95 operating system to SMS clients:

  • Use queries to identify which clients have the memory, disk space, and microprocessor required to run Windows 95.
  • Use the query results to create a machine group that contains all the computers that you want to upgrade to Windows 95.
  • Run ScanDisk on each client that will be upgraded.
  • Create a source directory for the Windows 95 operating system files.
  • Create a package and a job to distribute Windows 95.
  • Run a test to identify any issues in deploying Windows 95 on your network.

For information about queries and machine groups, see the SMS version 1.2 Administrator's Guide.

Running ScanDisk

The SCANDISK.EXE program checks for lost chains and clusters on the hard drives of the target clients. Because the Windows 95 Setup program runs ScanDisk and will fail if it detects a problem, you should run ScanDisk before installing Windows 95 on SMS clients.

You can use SCANDISK.PDF to distribute and run the ScanDisk program on clients that you plan to upgrade.

Note

If the target client is running Windows for Workgroups version 3.11, use the version of ScanDisk created for MSDOS version 6.22 rather than the one shipped on the Microsoft Windows 95 compact disc.

For information about using ScanDisk, see the Microsoft Windows 95 Resource Kit.

Preparing the Distribution Server

Create a source directory on the distribution server for the Windows 95 operating system files, and share the directory, using a share name that is identical to the directory name. Then copy all relevant files from the Windows 95 compact disc to the new source directory There are two recommended ways to copy the files:

  • Use the NETSETUP program (see the Microsoft Windows 95 Resource Kit for details) to decompress and copy the necessary files to the source directory. This option will give you maximum flexibility in customizing your installed components. You should use the Netsetup option if you want to create a setup directory that you can use to install shared Windows 95 configurations, where clients run Windows 95 across the network.
  • Copy the compressed files directly from the WIN95 directory on the compact disc to the source directory. This method saves disk space, but you lose flexibility in customizing installation options.

From the site server, copy the following files from the LOGON.SRV\MSTEST directory to the source directory:

  • WIN95.INF (for automated installs)
  • WIN95MIN.INF (for manual installs)
  • DOS2W95.EXE (to set up MS-DOS clients)
  • WIN2W95.EXE (to set up Windows clients)

Modify the WIN95.INF and WIN95MIN.INF files (Windows 95 setup script files that follow the MSBATCH.INF format) as necessary. The WIN95MIN.INF file is used in manual installs where the user provides or verifies installation choices. The WIN95.INF file is used for automated installations of Windows 95. The WIN95.INF file supports both Microsoft Networks and Netware Networks by default. It also sets clients to validate Windows NT domain logons. You may need to make appropriate changes to the WIN95.INF file to reflect time zone and custom network or installation settings. Be sure to add your Windows 95 product ID to both .INF files.

The automated Windows 95 setup process attempts to determine specific client information when possible. However, you might need to modify the WIN95.INF file for your network attributes or machine group configuration. In particular, you will probably need to modify the product ID and time zone. Eeview the default network client configuration and logon domain settings and add information to the file to override default installation settings. See the Microsoft Windows 95 Resource Kit for information about modifying an .INF file for various supported configurations.

The Windows 95 installation process requires the User Name, Domain/Workgroup Name and Computer Name for the targeted client. In the provided WIN95.INF template, these values have been left blank. These values can be provided in one of three ways.

  • Edit the WIN95.INF file to provide one or more of the missing values.
  • Allow the installation program to fill in the blank items using values in either the client's SMS.INI file or the SYSTEM.INI file. The installation program searches for the User Name in the following manner:
    • Looks in the input Windows 95 script file (usually WIN95.INF).
    • Looks in the SMS.INI on the client.
    • Looks in the MSBATCH.INF file in the Windows directory (Windows 95 clients will have this file from their last installation).
    • Looks in the SERIALNO.INI file in the Windows directory (Windows for Workgroup clients will have this file from their last installation).

If a User Name cannot be located, the installation program uses the Computer Name as specified in the .INF or the MachineName field in the SMS.INI file. If the client is running NetWare, the installation program uses the logon name of the current user.

  • Allow the installation program to prompt the user during the installation process.

Creating a Package to Install Windows 95

Use an SMS package to install Windows 95 on the target clients by running the setup command on each client. Make sure this package points to the proper network location for the Windows 95 source code, including the appropriate .INF files, whether the standard MSBATCH.INF or another version of this file is used.

To create a package to install Windows 95

1. Create a source directory for the required installation files and share the directory.

2. In the SMS Administrator, open the Packages window. From the File menu, choose New.

The Package Properties dialog box appears.

3. Choose Import.

The File Browser dialog box appears.

4. Select the \\servername\sharename\IMPORT.SRC\ENU\WIN95.PDF file and choose OK.

5. Choose Workstations.

The Setup Package for Workstations dialog box appears.

6. In the Source Directory box, enter the full UNC name for the source directory (in this case, the directory with the Windows 95 source files), and choose OK.

If you choose to browse through the list of files, edit the resulting path so that it shows the UNC name (which would begin with \\servername\sharename) rather than the relative name (which would begin with the drive letter you have assigned to the server during the current session).

7. Choose OK in all open dialog boxes.

When the package has been created and appears in the Packages window, you can use it to create a job.

Running the Package on Clients

Since certain warning and error conditions can pause or terminate automated installations of Windows 95, observe the following guidelines when using SMS to install Windows 95:

  • Ensure that all applications have been closed before starting the automated installation. If an application is open, the installation will pause until the user closes the application.
  • When you upgrade a client to MS-DOS 6.22, the MS-DOS setup program archives the previous MS-DOS directory as \OLD_DOSx (where x is a number). If the target computer has this directory, the Windows 95 installation will pause and ask the user if this directory should be deleted. If you want to automatically install Windows 95, make sure that the target clients do not have this directory. Use SMS to query for computers with an old MS-DOS directory and to delete these directories.

For the command in the package to be run on the target clients, you must create a Run Command on Workstation job. You can do this by dragging the package to the Machine Group in the site and filling in the resulting Job Details dialog box.

Once a job is distributed, the associated instructions are kept in the instruction file on each server until the job expires or is canceled, even after the job has completed on all target clients. This consumes about 3K per job per logon server. Use the Expires After setting in the Job Details dialog box to specify an expiration date that is realistic for your organization and for the job.

Testing the Windows 95 Deployment

After you run the test, evaluate the distribution results on the upgraded clients. Note that a Complete job status does not necessarily indicate successful deployment of Windows 95. You must perform additional analysis to determine the results of deployment:

  • Make sure that the SMS client inventory has been updated for all clients in the target group.
  • Use the following queries to determine whether the upgrade succeeded.

The following query identifies successful upgrades:

Microsoft|Operating_System|1.0:Operating System Name is 'MS Windows 95'

The following query identifies unsuccessful upgrades:

Microsoft|Operating_System|1.0:Operating System Name is 'MS DOS'
AND
Microsoft|Operating_System|1.0:Version is not '7.00'
  • Examine the computers that were not successfully upgraded on a case-by-case basis. If you marked the Inventory This Package check box in the Setup Package for Inventory dialog box when you created the package, you can examine a copy of the setup log file created on each target computer. Study this file to determine the cause of any problems. For example, there might have been changes in available disk space or in the availability of some other resource between the time the computer was added to the target group and the time the upgrade was performed.
  • Test the clients that were successfully upgraded to ensure that the configuration you specified works as expected on these computers. See the following section for details.
  • Check the details of job events to troubleshoot problems. For example, if a job has failed because the .INF file was not available where it was expected, this would be reported in the job events.
  • Determine whether any individual clients, which may have failed during the Windows 95 upgrade process, are no longer operational.

Clients that are no longer operational are not updated in the SMS inventory. You might choose to perform the inventory at more frequent intervals before deployment to make sure that only currently operational computers are targeted. In some cases, you might want to develop an SMS query to identify clients that have not had their inventory updated.

  • Determine whether a faulty hardware component caused a failure of the Windows 95 upgrade process.

Testing the Installation

Test the upgraded clients to make sure that the configuration you have installed will serve your organization as expected.

On a client that has been upgraded to Windows 95:

  • Connect to and browse through the network.
  • Set up a printer and test printing to local and network printers.
  • Open, run, and close applications on both the client and the server.
  • Shut down completely.

Test all mission-critical applications for proper functioning. If you encounter problems, try removing related features from the proposed configuration as a solution. Document any changes made to the original configuration.

If the preferred client configuration works as expected, you may want to conduct additional testing of the optional software features and components in Windows 95. This can help you determine whether you are running Windows 95 optimally. For this kind of testing, conduct side-by-side evaluations on two clients, changing individual features on each one, to determine the following:

  • Performance in terms of responsiveness and throughput
  • Ease of use
  • Stability
  • Compatibility
  • Functionality
Testing Installations on Novell Networks

To evaluate network client software for Novell NetWare, run your network performance tests in the following configurations:

  • Windows 95 installed with an existing 16-bit, Novell-supplied client (NETX), using ODI drivers.
  • Windows 95 added to an existing installation of Windows 3.1 and NetWare, using Client for NetWare Networks and protected-mode networking support components (NDIS adapter drivers).
  • Windows 95 as a new installation using all protected-mode components, including both Client for NetWare Networks and Client for Microsoft Networks, plus peer resource sharing support.

Perform several common tasks, such as connecting to the network and administering a remote NetWare server, to test for ease of use. Similarly, you'll want to run any business-specific NetWare applications under Microsoft Client for NetWare Networks to make sure that they run compatibly. Any stability issues should become apparent during this testing.

When you have identified a configuration that performs well during testing, test the same configuration on clients with different types of hardware configurations.


Deploying Microsoft Office for Windows 95 with SMS

Before you deploy Office to SMS clients:

  • Review the Office feature set and decide which components to install on the clients.

You can take advantage of user profiles to require that a mandatory desktop configuration be loaded each time a user logs on. (For more information, see your Microsoft Office for Windows 95 documentation.)

  • Decide on configuration and installation options, such as file locations, installation media, and installation method. (For more information, see the Microsoft Office for Windows 95 Resource Kit.)
  • Decide which existing files, macros, and custom programs you will need to use in the new software, and identify any extra steps that might be required to use the existing files and macros in Office.
  • Use SMS queries to identify which clients have the hardware required to run Office.
  • Run a test to identify any issues in deploying Office on your network.

The Microsoft Windows 95 and Office for Windows 95 Evaluation and Migration Planning Kit (MPK) has several documents that can aid in your review of Office. For a copy of the MPK, contact Microsoft Customer Service.

The Microsoft Office for Windows 95 Resource Kit, from Microsoft Press, is a technical supplement to the Office product documentation, written to assist administrators in installing, supporting, and managing Office on corporate networks. The Microsoft Office for Windows 95 Resource Kit is available at http://www.microsoft.com/technet/desk/office/orkf/orkftoc.htm.

Defining the Preferred Client Configuration

Before specifying the preferred configuration for clients, you should:

  • Understand the current server and client configurations.
  • Select the features that will be used in the preferred configuration on clients.
  • Select the features that will be used to enable users to work together.
  • Decide where Office files will be located and how they will be installed. That is, will Office files be installed on the client's hard disk, or will they be installed on a server and accessed remotely by the client, or a will a combination of both be used?
Researching Current Configuration Variables

To deploy Office successfully, you need to understand your current hardware and software configurations. Your deployment plan will be dictated by your current system environments.

  • Hardware configuration
    • For minimum hardware requirements, and to determine whether any clients need to be upgraded, see the Microsoft Office for Windows 95 Resource Kit.

Note Microsoft Schedule+ requires a Windows-compatible network and a MAPI 1.0-enabled mail server for scheduling and group functionality.

  • Laptop and desktop users have different configurations, including disk space and access to the network. Installation options will need to be selected with the specific client in mind.
  • Network topology
    • You can install software on clients from a network server, or you can run Office applications as SMS network applications. You may need to have different configurations for each of these cases.
    • Installing or running Office remotely over the network may not be practical for clients connected over a slow-link network.
    • Use of different network operating systems can create issues such as server file sharing methods and client-server permission schemes.
    • Installing Office over the network and running Office applications over the network place different demands on network bandwidth, both in response time and in length of time connected.
    • Migrating existing configurations

Determine whether you need to convert existing files, macros, and custom programs. For more information, see the Microsoft Office for Windows 95 Resource Kit.

  • Supporting multiple platforms

In many large organizations, users are running Office on a variety of supported platforms. For more information about these issues, see the Microsoft Office for Windows 95 Resource Kit.

Selecting Office Standard Features

By reviewing the feature set of Office, you can determine how to configure clients for the needs of your users. Because you can choose which components of Office to install, you have a lot of flexibility in tailoring client installations to include the best set of features for your users, while reducing disk space usage.

Selecting Office Workgroup Features

The workgroup features in Office establish how your users will communicate and work together.

Group scheduling with Schedule+

The group calendaring functions of Schedule+ require an underlying mail client, Microsoft Exchange, which is part of Windows 95. The small-business mail system that comes with Windows 95 allows users to exchange mail and meeting requests through a single post office. Microsoft Exchange also can work with other mail systems as long as the mail system uses a valid MAPI 1.0 driver. Such systems include Microsoft Mail and Microsoft Exchange Server. For more information about Microsoft Exchange with Windows 95, see the Microsoft Windows 95 Resource Kit.

Using Word as your e-mail editor

Microsoft Word for Windows 95 can be used to replace the default text editor used in the Microsoft Exchange mail client, which gives the user access to all the Word editing and formatting features. To use this feature, Microsoft Exchange in Windows 95 must be installed first on the client. Then, when Office is installed, choose the Custom Install; WordMail is one of the customization options for Word.

Workgroup templates

Users can share template files for Office documents using the Workgroup Template setting in Office. This setting, maintained in each user's registry, specifies a folder in which Office document templates can be stored for users. By defining this to be a folder on a network server, users in a workgroup can have access to a common set of templates. You can use the Network Installation Wizard to define this setting for your users in a custom installation script rather than having them set it individually.

MAPI and VIM

The Office applications include commands to send and route documents using e-mail. These commands work with Simple MAPI and MAPI 1.0 or later systems, such as Microsoft Mail 3.x and the Microsoft Exchange mail client included with Windows 95, and with 16bit VIM-based mail systems such as cc:Mail and Lotus Notes.

Briefcase support

Office supports the Windows 95 Briefcase, which allows users to synchronize different versions of a file whether or not the files are on the same hard disk drive or on the network. Microsoft Access, specifically, provides individual database replication using Briefcase.

Determining Configuration and Installation Options

When you understand the variables in your organization and how they will affect the manner in which you deploy Office, you can decide on the configuration for the preferred client. You will make decisions in the following areas:

Location of Office files

When deciding where to place Office files, consider how the client will be used and evaluate the benefits of each placement option, including how each option will effect your ability to support these configurations in the future. Office can be local (files installed on the client's hard disk) or shared (files are located on a network server, and users share those files over the network). You can also put some files on the local hard disk and some files on the server.

Installation options

There are several basic installation options available in the Office Setup program when Office Setup is run interactively by the user. You can also create your own customized options if the Office Setup program is to be run in batch mode using a customized script.

Installation method

Three methods can be used to perform the installation on the clients:

  • Interactive — allows the user to make all installation decisions.
  • Batch — provides a preset installation script for the user.
  • Push — initiates the installation for the user without user intervention.

A complete discussion of all these options can be found in the Microsoft Office for Windows 95 Resource Kit.

Creating the Administrative Installation Server Share

To install Office over the network, you first create a network installation server share by performing an administrative setup of Office from the Office Installation compact disc or floppy disk set. By using the Network Installation Wizard, you can modify the files in this share to customize the client installations, including whether clients will run Office locally or over the network. For information about creating and customizing a network installation location, see the Microsoft Office for Windows 95 Resource Kit.

Preparing the Clients

Make sure that each client has enough hard disk space, RAM, and processing capability to run Office:

  • To use Microsoft Office Standard, you need 28 MB of hard disk space for a compact installation, 55 MB for a typical installation, and 89 MB for a custom installation (maximum).
  • To use Microsoft Office Professional, you need 40 MB of hard disk space for a compact installation, 87 MB for a typical installation, and 126 MB for a custom installation (maximum).

Note

Office requires 8 MB of memory to run two applications on Windows 95. More memory is recommended to run three or more applications simultaneously on Windows 95.

In addition, before installation run virus detection, disk scanning, and defragmentation programs on the client to prevent any later problems. Although the computer may appear to be operating properly, software upgrades often uncover hardware or software problems because of the way they read and write data to the hard disk. Checking the computer before installing Office will help you stay focused on issues related to the installation process.

Be sure to back up critical data and configuration files for the client, in case the installation fails or you need to revert to the old system for some reason. Also you should create a Microsoft Diagnostics report and copy it to a floppy disk by running MSD.EXE on the hard disk. If you need to automate the restoration, consider using a commercial backup program, instead of copying the files by hand.

Any or all of the following can be used with Office for; however, they are not required:

  • Windows-compatible network required for workgroup functionality and WordMail.
  • Microsoft Exchange client required for workgroup functionality and WordMail on Windows NT.
  • 2400-baud or higher modem (9600-baud modem recommended).
  • Audio board with headphones or speaker.

Using SMS to Install Office

Use SMS to distribute an Office installation package to clients and to run the package with or without user interaction.

You can share Office in two ways:

  • Install all the main Office components (such as Word and Microsoft Excel) on the client's local hard disk but run the shared components (such as Spelling and ClipArt Gallery) from a network server.
  • Install Office using the Run From Network Server installation type and run all Office components from a network server.

The technique for creating each of these sharing environments within the SMS system varies.

How SMS Distributes Office

The following steps give an overview of how to use SMS to distribute Office when all Office components are run from a network server:

1. Create an administrative installation point for Office (run setup /a to a server location). See the following section for more information on the setup /a command.

2. In the SMS Administrator, create a package using the Office PDF that references the administrative installation point. For more information, see "Creating the Office Package" later in this chapter.

SMS will pick up all the files in the MSOffice folder on the administrative installation point and copy them to one or more SMS distribution servers.

3. Create a Run Command on Workstation job to distribute the package to selected clients.

4. When the package runs on the client, SMS runs, Office Setup from the copy of MSOffice residing on the distribution server. All the main and shared Office components are accessed from this server.

If Office is installed on a client's hard disk, the work of SMS is completed, and Office has been successfully installed. However, if you want users to share some or all of the Office components, there are more steps to complete.

Using Administrative Setup

Use the administrative setup command to build a source directory. Use the following command to start this setup:

setup /a

This command copies the source files into a directory and creates a SETUP.STF file for use in network installations.

Important

Do not use the SETUP.STF file located on the installation disks for a network or customized installation.

To prepare the administrative installation point

1. Choose the location for the administrative installation point.

Make sure that there is sufficient disk space. Office Standard needs about 90 MB for the administrative installation, and Office Professional needs about 130 MB. You need read, write, delete, and create permissions to use these folders while doing the administrative installation.

2. Make sure that all folders are empty.

If a previous version of Office exists, move any custom templates you want to save, then delete all of the Office files.

3. Create the MSAPPS32 directory for shared files.

4. Lock all folders to prevent network user access during the administrative installation.

5. Disable virus detection software to prevent erroneous virus detection triggers while setup is running.

6. Make sure the client on which you will be running SETUP.EXE is running Windows 95 or Windows NT 3.51 or later.

Sharing MSApps Components

When you create an administrative installation point, you define where the shared MSApps folder will be placed on the network; this location is written into the SETUP.STF file. When Office is installed to run shared components from this MSApps folder, the MSApps location defined in the SETUP.STF file is written into the user's registry.

SMS will distribute the Office installation package to the distribution server that is defined for a particular client, but it will not change the shared MSApps location defined in the .STF file. This means that even though a particular package may be sent to multiple distribution servers, all users of that package will share the same MSApps network location definition.

If you want different groups of users to share different MSApps folders, you first need to place copies of the MSApps folder on the servers you want to use for this purpose. You can do this by performing multiple administrative installations, creating the MSApps folder on the different servers. Or, you can do one administrative installation and then copy the MSApps folder to the other servers.

Once you have the MSApps folder on different servers, you can give users access to the appropriate MSApps location in one of two ways: using drive letter mapping and creating one SMS package or using UNC paths and creating multiple packages.

Drive Letter Mapping with One Package

By mapping the same drive letter in every user system to the appropriate MSApps server, you need only one SMS package for all users.

To use drive letter mapping to define multiple MSApps locations

1. During administrative setup (setup /a) of Office, specify the location of MSApps to be a certain drive letter. For example, drive H.

2. Copy the MSApps folder, with subfolders, to multiple servers, creating the same folder structure on each server.

3. On each client, map the drive letter you specified in Step 1 to the server containing the MSApps folder appropriate for that client.

4. Create a single SMS package for Office using the administrative installation point you created.

For information about creating this package, see "Creating the Office Package" later in this chapter.

5. Distribute this package to all clients.

6. When Office is installed using the package, Office Setup will define the drive letter you specified to be the location of the MSApps folder, and that drive letter will be mapped to the server appropriate for each client.

UNC Paths with Multiple Packages

If you are using UNC paths to specify the location of the MSApps folder, or if you are using drive letters but cannot define a single drive letter for all clients and all MSApps servers, then you need to create a different SMS package for each MSApps location.

One option is to perform multiple administrative installations and create a separate SMS package for each installation. During each administrative installation, specify a different network location for MSApps so that each package will install Office with a different MSApps location. You then distribute the appropriate package to those clients who need to use a particular MSApps location.

The other option is to perform one administrative installation and make multiple copies of the SETUP.STF file, one for each MSApps location. The location of the MSApps folder is defined in the SETUP.STF file when you do the administrative installation. By using the Network Installation Wizard, you can modify the MSApps definition in each SETUP.STF file to point to a different network location. You then create multiple SMS packages using the same MSOffice folder, but substituting the appropriate SETUP.STF file each time.

To use multiple STF files to define multiple MSApps locations

1. Run administrative setup (setup /a) for Office.

2. Copy the MSApps folder, and all subfolders, to multiple servers.

3. Make copies of the SETUP.STF file (found in the MSOffice folder) — one copy for each MSApps location.

4. Run the Network Installation Wizard on each SETUP.STF file.

5. In the dialog box in which you define the location of the MSApps folder, specify for each SETUP.STF file a different MSApps location.

6. Copy one of these SETUP.STF files to the MSOffice folder.

7. Create an SMS package for Office using the MSOffice folder.

For more information, see "Creating the Office Package" later in this chapter.

8. Send this package to those users who will be using the MSApps location defined in the SETUP.STF file.

9. Repeat steps 6 to 8 for each SETUP.STF file.

Creating the Office Package

Microsoft Office for Windows 95 includes a sample PDF for use with SMS: OFF95STD.PDF in the Microsoft Office Standard product, or OFF95PRO.PDF in the Microsoft Office Professional product. The PDF has command definitions in it for the standard types of client setup: Typical, Compact, Custom, Complete (the same as Custom but with all options selected), and Workstation (called Run From Network Server in Setup). Each of these command definitions contains a setup command line that will cause Office Setup to run in batch mode with the specific installation type (except for Custom, for which Office Setup is run interactively).

For example, the command line for Typical is:

CommandLine=setup.exe /q1 /b1

The /q1 option directs Office Setup to run with no user interaction, and the /b1 option directs Office Setup to use the first installation type (Typical). For an explanation of all the available Office Setup command line options, see the Microsoft Office for Windows 95 Resource Kit. When this command is run from this SMS package, Office Setup automatically installs Office using the predefined options for the Typical installation type.

Using the Packages window in the SMS Administrator, you can create a new command in the Office package that will run your custom command line for Office Setup.

To add custom commands to the Office PDF

1. In the SMS Administrator, open the Packages window, and from the File menu, choose New.

The Package Properties dialog box appears.

2. Choose Import.

The File Browser dialog box appears.

3. Select the appropriate PDF (OFF95STD.PDF or OFF95PRO.PDF). It is located in the administrative installation point in the folder containing the main Office application files.

4. Choose OK.

5. Choose Workstation if you want to install Office on the client's hard disk.

The Setup Package dialog box appears.

Specify the location of the administrative installation point for Office as the source folder.

7. To define the new command line, choose New.

8. In the Command Name box, type a name for the new command.

9. In the Command Line box, type the command to run your custom Office Setup.

For example, to run SETUP.EXE from the administrative installation point with the modified NEWSETUP.STF file, in quiet mode, type:

setup.exe /t newsetup.stf /qt

10. To indicate that no user input is required to run the package, select the Automated Command Line check box.

11. In the Supported Platforms box, select the appropriate platforms: Windows 95, Windows NT, or both.

12. Choose OK, and then choose Close.

You can now create a Run Command On Workstation job to distribute this package.

Testing the Installation

After you have set up a client with Office, you will need to run a variety of tests to ensure that it runs correctly and that you can still perform all of your usual tasks. Use your own testing methodology or, from a computer on which Office has been installed, test the following to verify correct system operation:

  • Open, run, and close Office applications.
  • Use the major Office features, including opening, modifying, saving, and printing documents.
  • Open existing files in the new Office applications.
  • If the client is using shared components on the network, such as spell-checking, test these functions.
  • If the client is using a shared Windows 95 installation, test standard Windows 95 functions such as printing.
  • Shut down completely.

In addition to ensuring that the preferred client configuration works as expected, you also may want to conduct additional testing of optional software features and components. This can help you determine whether you are running Office optimally. For this kind of testing, conduct side-by-side evaluations on two clients, changing individual features on each one, to determine the following:

  • Performance of responsiveness and throughput for local disk and network actions.
  • Ease of use for performing common tasks.
  • Stability of the two clients under stress.
  • Compatibility with applications and hardware.


Deploying Microsoft SQL Server with SMS

You can use SMS to automatically install Microsoft SQL Server version 6.5 on multiple computers running Windows NT Server in your organization.

The Microsoft SQL Server compact disc contains the following files to help you deploy SQL Server with SMS (located at the root of the compact disc).

SQL Server file

Description

SQL65.PDF

Automates the creation of a SQL Server package in SMS. The SQL Server package can then be distributed and installed on SMS computers. The PDF also enables SMS to detect SQL Server on SMS computers and report it in the SMS computer inventory.

SQLFULLdrive.CMD SQLNOBKdrive.CMD

Detect the platform of the computer and run the appropriate version of SQL Server Setup with the appropriate parameters, where drive indicates the drive letter where SQL Server will be installed. The SQLFULLdrive.CMD batch file installs the full SQL Server product including the online books. The SQLNOBKdrive.CMD batch file installs the SQL Server product without the online books.

The installation scripts product (SQLFULLdrive.INI and SQLNOBKdrive.INI) for SQL Server Setup require that the installation drive be specified in the installation script. Batch files and scripts are provided for installation on drives C, D, and E. For example, if you wanted to install SQL Server on drive D, you would use the SQLFULLD.CMD batch file. A custom script (SQLCUSTM.INI) is also provided so that you can change the drive specification to a drive letter that follows E.

SQLFULLdrive.INI SQLNOBKdrive.INI

Installation scripts that install SQL Server to a specified drive. drive indicates the drive letter where SQL Server will be installed.

SQLCUSTM.CMD SQLCUSTM.INI

The SQLCUSTM.CMD batch file runs SQL Server Setup to install the full SQL Server using the SQLCUSTM.INI initialization file. If you are installing SQL Server on a drive letter after E, you can modify the SQLCUSTM.INI file to specify any drive letter that you want. You need to modify the entries that specify drive locations.

Requirements

The computers where SQL Server will be installed have the following disk space requirements:

  • Full installation: 90 MB
  • Installation without online books: 75 MB

For other installation requirements for SQL Server, see the Microsoft SQL Server documentation.

On the SMS site server where the job to install the SQL Server is created, the site server must have 180 MB of free disk space.

To create the Microsoft SQL Server package

1. Copy all directories and files from the Microsoft SQL Server compact disc to a package source directory.

To create the package source directory for SQL Server, create the package source directory on a server and share it with the same name. Copy the directories and files from the Microsoft SQL Server compact disc to the package source directory.

2. If you plan to install SQL Server on a drive letter after E (that is, F, G, H, and so on), modify the drive specifications in the custom installation script (SQLCUSTM.CMD and SQLCUSTM.INI).

You need to modify the following items:

  • In the [SQLPath] section, set the LogicalSQLDrive entry to the drive where you want to install SQL Server. For example, to install SQL Server on drive G,

    LogicalSQLDrive=g:

  • In the [MasterPath] section, set the LogicalDBDrive entry to the drive where you want to create the master database. For example, to create the master database on drive G,

    LogicalDBDrive=g:

  • In the [Scripts] section, set the CustScPath entry to the custom script path you want to use. For example, if you want to create the master database on drive G, specify:

    CustScPath=g:\

  • If you do not want to install the online books, in the [NewOptions] section of the SQLCUSTM.INI file, set the BooksOnline entry to 0.

For information about the format of the installation script, see the Microsoft SQL Server documentation.

3. In the SMS Administrator, open the Packages window, and from the File menu, choose New.

The Package Properties dialog box appears.

4. Choose Import, and select the \\servername\sharename\SQL.PDF file.

The Package Properties dialog box displays SQL Server 6.5 in the Name box.

5. Choose Workstations.

The Setup Package for Workstation dialog box appears.

6. In the Source Directory box, enter the full UNC name of the SQL Server package source directory (for example, \\myserver\sql65).

You can choose to have SMS inventory this package. If you select this check box, SMS will copy the installation log file from the target computers to the SMS site server.

Important

The installation scripts cannot be run by the Package Command Manager service. They can be run only through the Package Command Manager client software. This means that you must leave the System Background Task option disabled in the Command Line Properties of the commands in the SQL Server package.

7. Choose Close.

8. Choose OK in all open dialog boxes.

The SQL Server package now appears in the Packages window. You can now use the SQL Server package to create Run Command On Workstation jobs to install SQL Server.

To distribute the Microsoft SQL Server package

1. In the SMS Administrator, open the Queries window, and from the File menu, choose New.

Define a query to find the computers where you want to install SQL Server.

Because the installation scripts are based on the installation drive, you should use a query to identify the computers that have the specified installation drive and also have enough free disk space on those drives. You can also create queries that impose other requirements such as amount of RAM or an existing SQL Server.

For example, the following query is designed to find all computers running Windows NT Server that have enough free space on drive D for a full installation of SQL Server:

(
    MICROSOFT|DISK|1.0:Disk Index is 'D'
    AND
    MICROSOFT|DISK|1.0:Free Storage (MByte) is greater than or equal
        to '90'
)
AND
(
    MICROSOFT|OPERATING_SYSTEM|1.0:Operating System Name is
        'Microsoft Windows NT'
    AND
    MICROSOFT|OPERATING_SYSTEM|1.0:Version is same as or comes after
        '3.51'
)

Note The installation drive has these disk space requirements:

Full installation: 90 MB

Installation without online books: 75 MB

For other requirements for SQL Server such as RAM, see the Microsoft SQL Server documentation.

2. To run the query, from the File menu, choose Execute Query.

3. Use the query results to add the selected computers to a machine group.

4. Use the new machine group to specify the target computers where you want to install SQL Server.

You can also specify the query as a target — SMS will evaluate the query when it activates the job used to install the SQL Server package and use that result as the list of target computers.

5. In the SMS Administrator, open the Jobs window, and from the File menu, choose New.

6. Choose Details.

7. In the Job Target box, specify the query or machine group.

8. Select the Run Workstation Command check box.

9. Select the command that specifies the drive where you want to install SQL Server (for example, select Complete Install on D: Drive if you want to install the full installation of SQL Server on drive D of all the target computers).

Note that if you set up the SQLCUSTM.INI setup script, you must select the Custom Install command to use that script.

10. Choose OK in all open dialog boxes.

When the job completes, SQL Server will be installed on all target computers.


Working with Network Monitor

This section describes the Network Monitor initialization file and how to set a server-down trigger.


Editing Parser Initialization Files

Each Network Monitor protocol parser uses an initialization (.INI) file. This section explains the sections of parser .INI files and situations in which you might need to modify these files.

The [ETYPES] Section

An Ethertype is a four-digit hexadecimal number that uniquely identifies a protocol implementation. If you write a new implementation for an existing protocol, you register the implementation with the Xerox Corporation, and you are assigned an Ethertype. This Ethertype appears in any frame that uses the new implementation, and enables software that receives the frame to distinguish the frame from any frame that does not use the new implementation.

The ETYPES section of a parser .INI file lists protocols and their associated Ethertypes. This information is used by the Network Monitor application programming interface (NMAPI) to ensure that a frame is passed to the correct parser for processing.

For example, the MAC.INI file contains the following entry:

0x600    =    XNS

If the media access control (MAC) protocol parser for Network Monitor encounters 0x600 in a frame, the parser reads its .INI file to identify the protocol associated with this Ethertype. It passes this protocol name to the NMAPI. The NMAPI passes the frame to the correct XNS parser.

If you add a parser to Network Monitor, or replace a Network Monitor parser with an implementation of your own, you must add the protocol name and the associated Ethertype to the ETYPES list in the Network Monitor .INI files. Make appropriate additions to the .INI file for every parser that can pass frames to your parser.

The [FORCE_RAW_IPX] Section

The information in this section applies only to the MAC.INI file.

Use the FORCE_RAW_IPX section of the MAC.INI file to specify how Network Monitor should respond when it receives an Ethernet or Fiber Distributed Data Interface (FDDI) frame that contains ambiguous data in the first two bytes after the frame's Length field.

An Institute of Electrical and Electronics Engineers (IEEE) 802.3 frame contains the following components:

Destination Address

Identified in the first six bytes of the frame.

Source Address

Identified in the second six bytes of the frame.

Length

Identified in the thirteenth and fourteenth bytes of the frame.

LLC Header

Identified in the next three bytes of the frame. Contains the destination service access point (DSAP), source service access point (SSAP), and control information.

All implementations of the IEEE 802.3 standard use the first three fields described in the preceding list to store the same types of information. However, implementations of IPX differ in their use of the bytes that follow the Length field. Differences in implementation can render the IPX protocol parser unable to interpret the first two bytes following the Length field.

For example, in a raw IEEE 802.3 frame, the bytes following the Length field always contain the hexadecimal numbers FFFF, which marks the beginning of the IPX frame. Because IPX frames currently do not use the checksum field, these two bytes are always FFFF and constitute the IPX header.

A true IEEE 802.3 frame, on the other hand, uses these bytes to store the DSAP and the SSAP. In the event that the DSAP and SSAP fields both equate to FF, the IEEE 802.3 frame cannot be distinguished from the IPX header in a raw IEEE 802.3 frame.

In most cases in which the number FFFF appears in the first two bytes following the Length field, it indicates that the frame is a raw IEEE 802.3 frame. Therefore, the FORCE_RAW_IPX field of the parser MAC.INI file is set to Yes for both Ethernet and FDDI frames. This setting notifies Network Monitor to interpret a frame containing FFFF in the first four bytes following the Length field as a raw IPX frame. If you set these entries to No, such frames are interpreted as true IEEE 802.3 frames.


Setting a Server-Down Trigger

This section explains how to set a server-down trigger. The trigger stops a capture on a computer running Network Monitor when another computer stops functioning. A third computer, running the Windows NT platform, runs a batch file that uses the net view command to query the network for the monitored server. If the server goes down, the computer running the Windows NT platform uses the net send command to notify the computer running Network Monitor, and the running capture is stopped.

Throughout this example, the computers will be referred to by the following names:

  • NM_HOST: The computer running Network Monitor.
  • NM_ASSIST: The computer running the Windows NT platform that notifies NM_HOST if the server goes down. Network Monitor on NM_HOST will be set up to stop capturing if it captures a frame that contains a particular data pattern. NM_ASSIST is set up to send NM_HOST a frame containing this pattern if a server goes down.

This computer does not have to be running the Windows NT platform, but it must be a computer on which the net send command is available. This command is available for Windows version 3.x running LAN Manager version 2.x. This command is not available for Windows for Workgroups version 3.x.

  • SOME_SERVER: The server being monitored. This computer can be running either Windows or the Windows NT platform.

The following figure illustrates the relationship among these three computers.

This example is designed so that you can work through it simply by substituting the computer names on your network for the computer names used in the example.

Implementing a Server-Down Trigger

To set the server-down trigger illustrated in this example, perform the following procedures:

1. On NM_HOST, set a capture filter that captures frames sent from any computer to the computer running Network Monitor, and then start a capture.

2. On NM_ASSIST, use the net send command to send a text string (serverdown in this example) to NM_HOST.

3. Use Network Monitor to capture and display the frame that contains the serverdown test string. Use this frame to determine the offset at which serverdown appears in the frame.

Note

The first three steps are intended simply to provide NM_HOST with a test frame. This frame's attributes are used later to provide necessary trigger specifications, and step 5 ensures that if SOME_SERVER stops functioning, a frame identical to the test frame is sent to NM_HOST.

4. On NM_HOST, set the capture trigger, set the same filter you used in step 1, and then start a capture.

5. Run a batch file on NM_ASSIST that uses the net send command to send the serverdown string to NM_HOST if the server goes down.

The following sections explain how to perform each of these steps.

Step 1: Filtering and Capturing

The server-down trigger requires two pieces of information: a pattern and an offset. A pattern is a particular arrangement of hexadecimal or ASCII data within a captured frame. The offset designates how many bytes into a frame the pattern occurs; this number is always hexadecimal.

The pattern in this example is arbitrary; when the trigger is set, the computer running Network Monitor stops capturing if it detects the text string serverdown within a frame. The text string, serverdown, represents the trigger's data pattern.

The offset is not arbitrary; because it measures how far into the frame the pattern appears, it can possibly distinguish between two frames containing an identical text string.

To determine the pattern offset, set up a Network Monitor filter to capture a frame containing the specified pattern.

To filter for the serverdown pattern

1. From the Network Monitor Capture menu, choose Filter.

The Capture Filter dialog box appears.

2. Select the Address Pairs line.

3. Under Add, choose Address.

The Address Expression dialog box appears.

4. In the Station 1 box, select the local computer name.

5. In the Direction box, select <-->.

6. In the Station 2 box, select ANY.

7. Select Include.

8. Choose OK in all open dialog boxes.

9. In the Capture window, from the Capture menu, choose Start.

Step 2: Sending a Test String

When a capture has been started on the computer running Network Monitor, a test frame must be sent to this computer. This frame, when captured, provides the pattern offset that is necessary for the server-down trigger to function correctly.

To provide the running capture with a test frame, on NM_ASSIST, use the net send command to send serverdown to NM_HOST. The net send command takes two parameters — the name of a computer and an ASCII text string — and has the following syntax:

net send computername string

In this example, string is serverdown. Remember that on NM_HOST, a filter has been set that captures all frames sent to that computer. This filter will capture the frame that contains serverdown, and you will use this frame to determine the offset of serverdown. In later steps, you'll need this offset to set up the trigger.

Step 3: Capturing and Displaying the Test String

In this step, identify the offset of serverdown — that is, how many bytes into the frame the first character in serverdown appears. This is the offset that you provide later when you set the server-down trigger.

To determine the offset of the serverdown test string

1. In the Network Monitor Capture window, from the Capture menu, choose Stop and View to display the Frame Viewer window.

2. In the Detail pane of the Frame Viewer window, expand the displayed protocol headers until the string SERVERDOWN appears in the lower-right corner of the Hex pane.

Tip

In the Detail pane, you need to expand only levels containing the SMB protocol header. If a plus sign (+) appears to the left of a level, the level can be expanded.

3. In the Hex pane, click the S in SERVERDOWN.

The pattern offset appears in parentheses in the status panel of the Frame Viewer window to the right of the word Offset. This is the hexadecimal number you use when you set the trigger.

Step 4: Setting the Capture Trigger

Once you have determined the offset of the test string, you can actually set the trigger and begin capturing.

To set the server-down trigger

1. In the Network Monitor Capture window, from the Capture menu, choose Trigger.

The Capture Trigger dialog box appears.

2. Under Trigger On, select Pattern Match.

3. In the Pattern box:

  • Select From Start of Frame.
  • Select ASCII.
  • In the Offset (In Hex) box, type the offset that you obtained in the preceding section.
  • In the Pattern box, type serverdown.

4. In the Trigger Action box, select Stop Capture.

5. Choose OK.

6. From the Capture menu, choose Start.

Step 5: Running the Batch File

Network Monitor monitors the server with the help of a computer running the Windows NT platform and a batch file. This computer running the Windows NT platform is the one that you used in "Step 2: Sending a Test String" to send the serverdown text string to the computer running Network Monitor.

The following is an example of a batch file that you might use:

:TOP
NET VIEW \\SOME_SERVER
If errorlevel 1 GOTO FAIL
GOTO TOP
:FAIL
NET SEND NM_HOST serverdown

This batch file contains a simple loop and two labels: TOP and FAIL. When the file begins processing, it runs the net view command, specifying the server name as a parameter, then processes the IF statement. If the net view command locates the server, the batch file returns to the TOP label and runs the net view command again. This process repeats until the net view command returns ERROR LEVEL 1, which indicates that net view was unable to locate the server and that the server is probably no longer functioning.

If the net view command returns ERROR LEVEL 1, the batch file runs the net send command, with serverdown as a string parameter, on the computer running Network Monitor. Network Monitor captures the frame containing serverdown as the offset specified in the trigger, and the trigger action is implemented; a message appears to indicate that the capture has stopped.

Note

This example uses one batch file to monitor one server. Because you can run multiple MSDOS sessions under Windows NT, you can run the batch file in multiple sessions, monitoring multiple servers. You need only to specify a different test string for each server, as well as the appropriate computer name for each instance in which the net view command appears.


Configuring SMS Clients for Remote Control

Each time an SMS client runs the SMS Client Setup program, the settings on the client can be changed. To make permanent changes, the user must use the Client Setup Options (CLIOPTS.EXE) utility, included in this Resource Kit.

The syntax for CLIOPTS.EXE is as follows:

cliopts /set optionname optionvalue

or

cliopts /list optionname

where optionname is either usertsr, useripx, or wuser, and optionvalue is any legal switch that can be passed to the named option. These are documented in the SMS version 1.2 Administrator's Guide.

For example, to see the current configuration of useripx, type:

cliopts /list useripx

To set USERTSR.EXE to use Lana number 1, type:

cliopts /set usertsr /L1

Changes do not take affect until the user restarts the computer, restarts the Windows operating system, or both, depending on which values are set.

Note

The cliopts program is recommended for clients whose options differ from the norm. If you want to change properties for all clients, use the Client button in the Site Properties dialog box in the SMS Administrator. Send cliopts in a package only to those clients that require changes to the default client settings.


Configuring the Event-to-Trap Translator

You can remotely modify the event to SNMP trap configuration on clients, using a job that uses EVENTCMx.EXE. You can run any of the following remote event configuration tools from the SITE.SRV\MAINCFG.BOX\MSTEST directory:

Executable file name | Supported platform
EVENTCMA.EXE | Alpha
EVENTCMI.EXE | Intel (x86)
EVENTCMM.EXE | MIPS

The remote event configuration tool uses the following syntax:

eventcm[i|a|m] filename options

Where filename is a .CNF configuration file that contains the event configuration to run on the client, and options can be one or more of the following:

/nolog

No logging.

/nomif

No MIF file generation.

/default

The configuration is modified only if the current configuration type is not CUSTOM.

/setcustom

Sets the current configuration type to CUSTOM.

/nostopstart

Do not stop and start the SNMP service.

For more information about the syntax of the configuration files (.CNF), see Chapter 4, "File Formats."


Debugging SNMP Traps

The Event to Trap Translator converts selected Windows NT events, from the three Windows NT event logs, to SNMP traps and sends them to a site. At the site, SNMP traps are filtered for specific traps, and these are written to the database. Also, the traps can be sent to other network management consoles besides the SMS Administrator.

To use the SNMP traps functionality, complete the following steps.

On the client that will be used to send traps:

  • Install TCP/IP and SNMP.
  • Use the Windows NT Control Panel to configure the SNMP client.
  • Install the SMS SNMP and translation agent files.
  • Use the Personal Computer Properties in the SMS Administrator to configure the SNMP clients.
  • If you want to use security traps from the client, use the Windows NT User Manager to enable security logging on the client.
  • If you are going to trap file activity on the client, use the Windows NT File Manager to enable security auditing for those directories.

At the site to receive traps

  • Install TCP/IP and SNMP.
  • Configure a filter for incoming traps.


Installing TCP/IP and SNMP

If the Windows NT-based client that will generate traps is running Windows NT version 3.51, SP4 must be installed. For detailed installation procedures, see the SMS version 1.2 Administrator's Guide, Chapter 14.

You must configure the SNMP service and add at least one community name containing at least one address to send traps to.

To add a community name

1. On the client that will receive the traps, run ipconfig to display the IP address for the local computer.

2. On the client that will send traps, make sure the SNMP service is running.

3. On the client that will send traps, configure the SNMP service (in the Networks control panel) and add the address of the receiving client to the community.

4. Stop and then start the SNMP service so that all the settings will be active.

If SNMP is installed after the SMS client is installed, you might need to manually set the TranslatorEnabled value in the HKEY_LOCAL_MACHINE\Software\Microsoft\SNMP_EVENTS\EventLog registry key. This value is created by SNMP Setup and set to Yes by the cli_nt program the next time the user logs on or runs RUNSMS.BAT. Ensure that this value is Yes so that the event to SNMP trap translation will occur.

To start the Event to Trap Translator

1. In the SMS Administrator, open the Personal Computer Properties for the client that will be sending SNMP traps.

2. In the Windows NT Administrator group, select Event to Trap Translator.

The EVENTRAP.EXE program starts, using the client as the target. The Event to Trap Translator window appears.

Unless you use this tool to specify events to be converted to SNMP traps, no Windows NT events will be translated and sent. A few traps are sent by default.

3. Choose Custom.

4. Choose Edit.

5. In the Event Source list, choose Security.

6. Choose Security to list the Windows NT security events. One at a time, select an event, and choose Add to add it to the configuration.

7. When you are finished, choose Close.

The following event IDs can be quite useful: 560, 561, 562, 592, and 593. The 56x events are for the directory where you can test bursts of traps, and the 59x events can be used to tell if a process has a general protection fault and gets restarted. (It had a general protection fault if you weren't the one to start it.)

The LOGON.SRV\MSTEST\EVENTCMx.EXE program can be sent as a job to configure SNMP on a group of clients. For details on this program, see "Configuring the Event to Trap Translator" earlier in this chapter.

To audit Windows NT events

1. Start the Windows NT User Manager.

2. From the Policies menu, choose Audit.

The Audit Policy dialog box appears.

3. Choose Audit These Events, and then select all events to be audited.

4. Choose OK.

5. If you want to audit file and object access, open the File Manager and select the directory to be audited.

6. From the Security menu, choose Auditing.

7. Select the events to audit.

If you select the name after the events, nothing gets audited.

Note

Auditing is available only on NTFS partitions.

Do not use the domain\smsadmin and local\smsadmin accounts because Windows NT will never activate the local admin account for auditing.

Now go to the SMS Administrator for the site that the client is sending SNMP traps to, and set it to write some of these traps to the database. For details, see the SMS version 1.2 Administrator's Guide.


How SNMP Works in SMS

Client services related to SNMP:

  • SNMP service (process name SNMP)
  • TCP/IP NetBIOS helper (not a separate process, part of the network)

Site services related to SNMP:

  • SMS_CLIENT_CONFIG_MANAGER (process name Clicfg)
  • SMS_EXECUTIVE (process name SmsExec)
  • SNMP service (process name SNMP)
  • TCP/IP NetBIOS helper (not a separate process, part of the network)

Site processes not running as a service related to SNMP:

  • SNMPTRAP

SmsExec thread components related to SNMP:

  • TRAPFLTR

The net start command will display the service name SNMP Service, but it will also respond to the simpler SNMP when you are controlling it from the command line.

The SMS functionality for Windows NT event to trap translation is a DLL extension (SNMPELEA.DLL) to the SNMP service with the process name of SNMP and service name of SNMP service. The SMS extension to the SNMP service uses the Windows NT file SNMPAPI.DLL. As one thread reads the Windows NT event log, translates events, and adds SNMP traps to a list to be sent, another thread reads the list and has the SNMP service send the trap, and deletes it from the list. This second thread is sometimes called the trap sender. As the list grows, more memory is allocated to the SNMP service. After all the traps have been sent, the memory allocation will return to the original level, and the SNMP service idles. Since the Event to Trap Translator adds traps to the list faster than it sends them, a big burst can add quite a bit of memory allocation to the SNMP service.

The SMS feature trap translator is the TRAPFLTR thread component in SmsExec. TRAPFLTR starts SNMPTRAP.EXE after SmsExec starts TRAPFLTR. SNMPTRAP.EXE receives SNMP traps sent to that client, and passes them to the thread component TRAPFLTR in SmsExec. As the client receives traps, SNMPTRAP.EXE shows CPU activity. TRAPFLTR decides whether to write the trap to the database, or discard it. If it is a burst of traps, TRAPFLTR will get behind, and the memory allocation for SmsExec will grow. As the traps are discarded or written to the database, the memory allocation for SmsExec will be released and return to the original level.

If the Windows NT event log is set to a small size and to overwrite events as needed, and there is a burst of events, the Event to Trap Translator can fall behind and lose traps if they are overwritten before it translates the event.

If a client is sending traps to itself, use Network Monitor (running on a separate computer) to monitor the activity.


Testing the SNMP Client Setup

When testing the translation of events to SNMP traps on clients running Windows NT, remember:

  • If the events are not being written to the Windows NT event log, they can't be translated.
  • If the traps are not going out on the network, the site can't receive them.

To test whether security logging and auditing is working, add user permissions for a file or directory and see if security events show up in the Windows NT event log. Every time a file has its permissions changed, event IDs 560 and 562 should be created.

Next, test the trap sending on the client. In a directory that contains at least 50 files, set auditing for your user name. Add or remove a user from the permissions for the directory, subdirectories, and files. In the Performance Monitor, you should see CPU activity for SNMP. Private bytes for SNMP should slope up, then slope down, and then CPU activity should stop. This sequence means the Event to Trap Translator converted some events to traps, put them in the list, and sent them somewhere.

Network Monitor allows you to view whether events that have been translated into traps are sent to the destination.

At the site receiving the traps, SmsExec should grow in size and show an increase in CPU usage. The TRAPFLTR thread in SmsExec should show the increase in CPU usage. The TRAPFLTR log should show traps being written to the database, and the SNMP traps window should show new traps, after being refreshed.

For information about using the following tools, see the Microsoft Windows NT Resource Kit:

  • SNMP Monitor (SNMPMON.EXE)
  • SNMP Browser (SNMPUTIL.EXE)


Loading the SNMP Traps' Functionality and Sizing Hardware

Trapping for file activity is a good way to size the hardware for SNMP traps. Create several bursts of traps by changing the file permissions in large groups of files. By timing how long it takes to process the traps, you can calculate the trap throughput.

Caution

There is a large amount of file activity in all SMS directories on all SMS servers and clients. Trapping file activity in these locations will cause a flood of traps.

If the Automatically Configure Logon Scripts option is enabled, by default the Site Configuration Manager will check each user account for correct logon script configuration every 24 hours. This will produce two events for each user account in each SMS domain in the site.

Changing permissions on a group of files can cause bursts of traps. If the bursts are too large or too frequent, SNMP might stop responding. If so, stop and then start the SNMP service.

If you use the default of enabling the trap throttle, remember that if the throttle gets tripped, you have to manually reset it before any more traps are sent.


Backing Up and Restoring the SMS System

The SMS version 1.2 Administrator's Guide describes how to back up and restore an SMS site. This section provides more details about these processes.

Every time a database is expanded, it creates another fragment. The SMS database typically expands occasionally as the number of inventoried machines grows. To completely restore the database, the new device(s) have to have the same fragment pattern. If the database was created with 20 MB data and a 10 MB log, and then the data expanded by 30 MB and the log expanded by 5 MB, to restore data to the new database the first four fragments need to be the same type and size and in the same order. The new database can be bigger with more fragments, but the first four fragments have to match the four from the backed up database. Along with this, the SQL server must use the same sort order and code page that was in use by SQL server when the backup was made.

There is a SQL limit of 32 fragments in a database. Once this limit is reached, the database cannot be expanded any more. If the fragments are not contiguous, the only way to reduce the number of fragments and save the data is to transfer the whole database to a new database that uses one large data fragment and one large log fragment. (See the SQL Server documentation for more information.) After that, SMS must be pointed at the new database.

Before backing up the database

1. Start the MSSQL\BINN\ISQLW.EXE program and select the SMS database as the default.

2. Stop all other processes that might access the SMS database.

3. Run the following data integrity checks:

dbcc checkdb
go
dbcc newalloc
go
dbcc checkcatalog

Note

Errors that are not corrected before backup might prevent the restore.

4. Save a copy of the files in the \MSSQL\LOG\ERRORLOG directory, which will contain the SQL version, sort order, and code page being used at that time.

5. To consolidate any contiguous fragments, select the SMS database as the default in isqlw, and run the following command:

sp_coalesce_fragments SMSdatabase

Where SMSdatabase is the name of your database.

Note

If the fragments are not contiguous, this command will not help. If the database was created with a data then log fragment, and data was expanded then log expanded, there will be four noncontiguous fragments, this command will not help.

6. Select the SMS database as the default in isqlw and run the following command to display basic information about the database including the name, options selected, and a list of the fragments:

sp_helpdb SMSdatabase

7. Save the results for future reference.

Now back up the database.

You can create a script that will create the correct fragment pattern. If the database name or physical device names will be changed, you must edit the script to reflect these changes.

To generate the fragment correction script

1. Select the SMS database as the default in isqlw.

2. Run the following command:

sp_help_revdatabase SMSdatabase

3. Save the results.

Be sure to verify that the database is still intact after completing these tasks. If there were errors interjected into one of the steps, the restore might not be completely successful.

4. Select the SMS database as the default in isqlw, and run the following commands:

dbcc checkdb
go
dbcc newalloc
go
dbcc checkcatalog

5. Create the data devices for the SMS database: one for data and a separate one for log. Even if there are several fragments, all the data fragments can go on the data device and all the log fragments on the log device.

6. If necessary, edit the database name and device names in the script produced by sp_help_revdatabase, and run the script from isqlw.

7. Restore the SMS database.

8. In SMS Setup, run Operations/SMS Database and change the SQL Server name and the database name, if appropriate. This points SMS services to the new server and database.

Note

The REGEDT32.EXE program can save registry information in both binary and ASCII format. Be sure you are saving the SMS registry keys in a format that regedt32 can restore (binary).


Chapter 6 - Tuning

Microsoft Systems Management Server (SMS) is a complex and powerful tool. For SMS, as with most complex systems, performance monitoring and tuning is an important part of system maintenance to ensure optimum system performance. This chapter discusses methods for identifying and fixing tuning problems—problems that occur when the system is performing properly, but not efficiently.

To help you find and eliminate tuning problems, this chapter provides information about the following:

"Tuning and Bottlenecks" A single component can degrade system performance. When this happens, the limiting component is called a bottleneck. This section discusses bottlenecks and how to find them.

"Performance Monitor" Performance Monitor is a Windows NT administrative tool for monitoring the performance of computers running Windows NT. This section describes Performance Monitor and how to use it to find bottlenecks in an SMS system.

"Task Manager" Task Manager is a new tool introduced with Windows NT 4.0. It lets you start, stop, and monitor applications and processes on your computer. It also provides basic performance-monitoring capabilities. This section describes how to use Task Manager to find bottlenecks.

"Tuning Tips" This section describes ways to tune your SMS system once you have found bottlenecks that are impairing system performance.


Tuning and Bottlenecks

Tuning a system means locating the reason why the system is not performing up to expectations. Frequently, there is a single system component that is causing the system to perform poorly. The condition in which the limitations in one component prevent the whole system from operating faster is known as a bottleneck. The primary indicator of a bottleneck is an extended high rate of use on one hardware resource and resulting low rates of use on related components. It is accompanied by sustained queues for one or more services, and slow response time.

If a computer handles many different types of tasks, different components may become bottlenecks at different times. For instance, the CPU may become the bottleneck when a compute-intensive application is running; the disk may become the bottleneck if several applications are attempting to read and write data simultaneously. However, in general, the device with the lowest maximum throughput is the most likely to become a bottleneck if it is in demand. This is especially true of server applications that tend to run only a few demanding applications (like SMS or SQL Server). If a component is acting as a bottleneck, making other components faster can never yield more throughput; it can only result in lower utilization of the faster components.

Although 100 percent utilization of a resource is a clear warning of a bottleneck, it is neither a necessary nor sufficient condition. You can have bottlenecks on devices with utilization well below 100 percent and you can, at least in theory, have a device running at nearly 100 percent utilization that is not a bottleneck. That is, the device is not preventing any other resource from getting its work done, nothing is waiting for it, and even if it were infinitely fast, things wouldn't happen any sooner.

The following list describes some of the most obvious and common signs that can be observed and that may indicate a bottleneck:

Server hard disk is always busy.

Frequently, you can observe how busy a server's hard disk is by watching and listening to the server. If the server's disk is always busy, then there is a good chance that the server is not performing optimally.

Server applications run very slowly.

You may notice that the SMS Administrator (or other applications) runs very slowly on the server.

Clients cannot access server (or server responds very slowly).

SMS servers are used to perform a number of different functions. For instance, servers log clients on to the network, configure the clients to run SMS, collect the inventory data from the clients, and provide distributed packages to the clients. You may observe that some servers are so busy that they stop processing log ons, or process the logon requests very slowly. Users may notice that their logon scripts take much longer than they used to, or that SMS Client Setup or inventory is much slower. Additionally, users may not be able to install packages, or may not be able to gain access to shared packages.

SMS stops processing system files.

You should routinely check the SMS system directories to be sure that files are being processed correctly. The following table lists some of the directories that should be monitored; a backlog of files in these directories may indicate that the system is not performing optimally.

Directory | Comment
LOGS | Used by the SMS services and components to store logs. Contains primary and backup logs for up to 19 components. By default, each log uses up to 128K. Logging can take a great deal of disk space and can degrade system performance. Use the SMS Service Manager to change the log size or to disable logging.
SITE.SRV\INVENTRY.BOX | The location where Maintenance Manager puts client inventory files that it collects from SMS logon servers. The Inventory Processor monitors this directory. The files in this directory are deleted when the inventory data is written to the SITE.SRV\DATALOAD.BOX\DELTAMIF.COL directory. A backlog might indicate that the Inventory Processor is not running or is too busy to process the files.
SITE.SRV\INVENTRY.BOX \BADMIFS | The location where the Inventory Processor places .MIF files that cannot be processed. This directory should always be empty.
SITE.SRV\INVENTRY.BOX \BADRAWS | The location where the Inventory Processor places .RAW files that cannot be processed. This directory should always be empty.
SITE.SRV\DATALOAD.BOX \DELTAMIF.COL | Used by the Inventory Processor to store MIF files that are ready to be processed by the Data Loader. When the Data Loader is ready to process the files, it moves them to the PROCESS subdirectory. A backlog in this directory might indicate that the SQL Server is unavailable, or that the Data Loader is too busy to process the files.
SITE.SRV\DATALOAD.BOX \DELTAMIF.COL\PROCESS | Used by the Data Loader to store MIF files that it is ready to process. Once these files are processed, they are moved to the SITEREP.BOX directory. If the Data Loader is unable to process some files, they are moved to the BADMIFS directory. A backlog might indicate that the SQL Server is unavailable, or that the Data Loader is too busy to process the files.
SITE.SRV\DATALOAD.BOX \DELTAMIF.COL\BADMIFS | Used by the Data Loader to store MIF files that cannot be processed. Under ideal conditions, this directory is empty. Any files here indicate a problem.
SITE.SRV\SITEREP.BOX | Used by the Data Loader to store files that should be sent to a parent site. When the Site Reporter detects a queue of MIF files in this directory, it creates a system job that sends these MIF files to the parent site. A backlog might indicate that Site Reporter is not running or is overloaded, or that the site cannot connect to the parent site.
SITE.SRV\SCHEDULE.BOX | Used by the SMS components to store system job instructions for the Scheduler. The Scheduler monitors this directory and uses the instructions to start the specified system jobs. A backlog might indicate that the Scheduler is not running or is too busy to process the jobs.
SITE.SRV\SENDER.BOX \REQUESTS | The location where the Scheduler places send request files for the sender. The specific sender assigned to each subdirectory (outbox) monitors its directory and processes the requests. Files remain in this directory until the sender successfully sends the job. A backlog might indicate that the sender is busy or not running, or that it cannot connect to the target site.
SITE.SRV\SENDER.BOX \TOSEND | The location where the Scheduler places compressed packages and despooler instruction files to be sent to another site. When the sender processes a send request for a job, it sends the job's files from this directory to the target site. A backlog might indicate that the sender is busy or not running, or that it cannot connect to the target site.
SITE.SRV\DESPOOLR.BOX \RECEIVE | The location where the sender places despooler instruction files and compressed packages that are targeted for the site. The Despooler monitors this directory and processes the instruction files. The packages should be moved to the STORE directory as soon as the Despooler verifies that the package and instructions have been completely and correctly received. A backlog might indicate that the Despooler is too busy to process the packages.

In these cases, it may or may not be reasonably easy to determine the cause of the problem and to find a solution. For instance, if MIF files are backing up in the DELTAMIF.COL directory, you can be reasonably sure that the Data Loader is the bottleneck. A quick look may show that the Data Loader is not running, in which case you simply need to restart it. If the Data Loader is running, you may need to increase the capacity of the site server, or move the Data Loader to another server, in order to get better results. To specifically determine the reason that the Data Loader is not keeping up, you should use one of the troubleshooting tools or techniques described later in this chapter.


Performance Monitor

Performance Monitor is a Windows NT administrative tool for monitoring the performance of computers running Windows NT. It uses a series of counters to track data, such as the number of processes waiting for disk time, the number of network packets transmitted per second, and the percentage of microprocessor utilization. You can watch this data in real time, log it for future study, use it in charts and reports, and set alerts to warn you when a threshold value is exceeded.

Performance Monitor lets you:

  • View data from multiple computers simultaneously.
  • See how changes you make effect the computer.
  • Change charts of current activity while viewing them.
  • Export Performance Monitor data to spreadsheets or database programs, or use it as raw input for C programs.
  • Trigger a program or procedure, or send notices when a threshold is exceeded.
  • Log data about various objects from different computers over time. You can use these log files to record typical resource use, monitor a problem, or help in capacity planning.
  • Combine selected sections of several log files into a long-term archive.
  • Report on current activity or trends over time.
  • Save different combinations of counter and option settings for quick starts and changes.

Performance Monitor shows a broad view of the computer's performance. In some cases, you can use Performance Monitor to fully identify and fix a problem. In other cases, you may need to use a more specialized tool, such as a profiler, a working set monitor, or a network analyzer. The usage of those tools is beyond the scope of this chapter; for more information about specialized troubleshooting tools, contact the vendor of the tool.

The next sections provide some tips for using Performance Monitor. The sections assume you are using Windows NT Server 4.0 and SQL Server 6.5.

For more specific instructions about using Performance Monitor, see Performance Monitor Help, or see the detailed description in the Microsoft Windows NT Resource Kit.


Starting Performance Monitor

You can start the Windows NT Performance Monitor from the Administrative Tools menu on the Start menu or from the command line.

When you use Performance Monitor, you select object counters and options to customize each of the four Performance Monitor views: Chart, Log, Report, and Alert. You can save these counter and option settings to a file and design different settings files for all of your monitoring tasks.

You can save settings for one view or save a group of view settings in a workspace. The following table shows the file extensions associated with each view.

View | Settings file extension
Alert | .pma
Chart | .PMC
Log | .PML
Report | .PMR
Workspace | .PMW

You can start Performance Monitor with a settings file or open the settings file after you start. You can use only one settings file of each type at a time, but you can open multiple copies of Performance Monitor and use a different settings file or workspace with each copy.

When you start Performance Monitor from a batch file or from the command line, you can specify a settings file listing the counters and options for each view.

For example:

C:\> perfmon settings.pmw

To configure Performance Monitor to start automatically when a user logs on to the system, copy the Performance Monitor icon to the Startup program group, with the command line perfmon.exe my.pmw, where my.pmw is the name of a workspace file that exists on the computer.

To configure Performance Monitor to run on system startup (so it's running even if nobody logs on), use the MONITOR.EXE program provided in the Microsoft Windows NT Resource Kit. MONITOR is the configuration tool for installing and controlling the Data Logging service (DATALOG.EXE). The Data Logging service is a Windows NT service that performs alert and log view functions. For more information on remote logging and automatically starting and stopping the service, see the Microsoft Windows NT Resource Kit.


Performance Monitor Views

Performance Monitor lets you set up views for charts, alerts, logs, and reports. When you start using Performance Monitor to find bottlenecks in the system, you may find it useful to set up more than one type of view. Using multiple views at the same time gives you a better representation of what is actually happening in your system. For instance, Log view (which occurs over a long period of time) may show you trends which you would not notice in Chart view.

When you set up multiple views, you create a workspace. You can preserve the workspace, thus preserving the complete configuration of all views you are using. To preserve a workspace, save the view configurations in a workspace settings (.PMW) file.

Chart View

When you begin troubleshooting a performance problem, you will most likely want to start with Chart view. Chart view shows you the current activity of the selected counters and instances. You can customize each chart (by adding or deleting objects, counters, and instances) to create a chart that lets you monitor many different types of performance. You can change chart selections, such as chart scale or counter display colors, to make your charts more readable.

When you add objects to a chart, you can use the Explain button to learn more about what each counter is used for. You can use the Chart Options dialog box to change the update time, to display in histogram mode, or to change many other Chart view options.

Log View

You can use Log view to document activity and trends over a long period of time. Log view takes whole objects with all their counters for all instances, and it writes all of this data to a log file. These log files can get very large, so use caution when setting up logging.

It is often a good idea to begin by logging the Logical Disk, Memory, Process, Processor, System, and Thread objects. You configure the log in the Log Options dialog box. You must specify the log file name and update interval before you can start logging. When you are ready to start logging, select the Start Log button.

The Log View window displays the log file, file size, logging status, and log interval while logging is enabled. Monitor the size of the log file to ensure that it does not become too large. When you want to stop logging, go back to the Log Options dialog box and select the Stop Logging button.

To view the log, select Options, Data From, and specify the log file name.

The log can be exported with comma or tab delimited columns for analysis in a spreadsheet or database.

Alert View

You can configure Performance Monitor alerts to notify you if the system seems to be reaching a critical state in a key area. For instance, you can set alerts to be generated if Logical Disk: % Free Space, or Memory: Available Bytes falls below 20 percent, or if System: Processor Queue Length exceeds 3.

You can configure Performance Monitor to carry out one or more of the following actions when an alert is generated:

  • Run a program.
  • Log an event to the Windows NT application log on the system where Performance Monitor is running.
  • Send a network alert message to another computer.


Objects and Instances

Performance Monitor uses objects, counters, and instances to describe the components of a computer that can be monitored. Objects represent threads and processes, sections of shared memory, and physical devices in the computer. For instance, a computer has at least one object known as microprocessor. In some cases, computers have more than one instance of an object; for example, a computer may have multiple microprocessors. Counters are the things about an object that can be measured (or counted). When you specify what you want to monitor in Performance Monitor, you must always specify the object, counter, and instance that you want to monitor.

Performance Monitor collects data on activity, demand, and space used by the objects in your computer. Some objects always appear in Performance Monitor; others appear only if the service or process is running. The following table shows the objects that always appear when you run Windows NT 4.0.

Object name | Description
Cache | The file system cache is an area of physical memory that holds recently used data.
Logical Disk | Disk partitions and other logical views of disk space.
Memory | RAM used to store code and data.
Objects | Certain system software objects.
Paging File | File used to back up virtual memory allocations.
Physical Disk | Hardware disk unit (spindle or RAID device).
Process | Software object that represents a running program.
Processor | Hardware unit that runs program instructions.
Redirector | File system that diverts file requests to network servers.
System | Counters that apply to all system hardware and software.
Thread | The part of a process that uses the CPU.

Each instance of an object represents a component of the system. When the computer being monitored has more than one component of the same object type, Performance Monitor displays multiple instances of the object in the Instance box of the Add to Chart (View, Log, or Report) dialog box. It also displays the _Total instance, which represents a sum of the values for all instances of the object.

For example, if a computer has multiple physical disks, there will be multiple instances of the Physical Disk object in the Add to Chart dialog box. This dialog box shows two instances of physical disks and a _Total instance. You can monitor the same or a different set of counters for each instance of an object.

All counters for an object have the same instances. But, sometimes, the instances just don't make sense for a particular counter. For example, the totals of ordinal numbers, like _Total of Process: Process ID or Thread: Thread State, have no meaning. If you add them to you view, Performance Monitor displays the values as zeros.

Only 32-bit processes appear in the Instances box. Active 16-bit processes appear as threads running in a Windows NT Virtual DOS Machine (NTVDM) process. However, you can run each 16-bit application in a separate NTVDM process to make monitoring easier. For more information, see the Microsoft Windows NT Resource Kit.

Some objects are parts of other objects or are dependent upon other objects. The instances of these related objects are shown in the Instances box in the following format:

Parent object = => Child object

The child object is part of or is dependent upon the parent object. This makes it easier to identify the object.

For example, each logical partition of a disk is shown as the child of a parent physical disk.

In this example, two physical disks, 0 and 1, are each divided into two logical disks. The Instances box shows that logical disks C and G are partitions of physical disk 0, and logical disks D and E are partitions of physical disk 1.


Counters

Performance Monitor provides counters that collect, average, and display data about computers running Windows NT. Performance Monitor collects data on various aspects of hardware and software performance, such as use, demand, and available space. You activate a Performance Monitor counter by adding it to a chart or report or by adding an object to a log. Performance Monitor begins collecting data immediately.

In this chapter, counters are associated with an object in the following format:

Object: Counter

For example, the % Processor Time counter of the Process object would appear as Process: % Processor Time to distinguish it from Processor: % Processor Time or Thread: % Processor Time.

Tip

To display the definition for each counter, choose the Explain button in the Add To dialog box. The Explain button works only when you are monitoring current activity, not logs.

There are three types of counters:

  • Instantaneous counters display the most recent measurement.

For example, Process: Thread Count displays the number of threads found in the most recent measurement.

  • Averaging counters, whose names include per second or percent, measure a value over time and display the average of the last two measurements. When you start these counters, you must wait for the second measurement to be taken before any values are displayed.

For example, Memory: Pages/sec, shows the average number of memory pages found in the last two reads during the second measured.

  • Difference counters subtract the last measurement from the previous one and display the difference if it is positive. If it is negative, they display a zero.

Performance Monitor doesn't include any difference counters in its basic set, but they might be included in other applications that use Performance Monitor, and you can write them yourself. For information on writing performance counters, see the Microsoft Windows NT 4.0 Software Developer's Kit.

Performance Monitor includes default counters for each object. For instance, when you open the Add To dialog box, the Processor: % Processor Time counter is selected because this counter is used most often. Each object has a default counter which is highlighted when you select the object. These counters were selected as defaults because they are excellent indicators of the object's activity.

Some hardware and applications designed for Windows NT come with their own counters. Many of these extensible counters are installed automatically with the product, but some are installed separately. In addition, there are a few specialized counters on the compact disc in the Microsoft Windows NT Resource Kit. See your product documentation and Performance Monitor Help for detailed instructions on adding extensible counters.


Using Performance Monitor to Tune SMS

This section describes the objects and counters that should be used with SMS. In many cases, you can use a small subset of these counters to determine the status of an SMS system. The counters that are most useful to monitor in an SMS environment are:

Object | Counter | Measure on
Memory | Committed Bytes | Site server
PhysicalDisk | % Disk Time (for all physical disks) | Site server and SQL Server
Processor | % Processor Time (for all processors) | Site server and SQL Server
Redirector | Current Commands | Site server and SQL Server
SQLServer | User Connections | SQL Server
SQLServer | Cache Hit Ratio | SQL Server

These counters (and other useful objects and counters) are described in the following sections.

Cache Object

Data Map Hits %

The percentage of data maps in the cache that could be resolved without having to retrieve a page from the disk, meaning that the page was already in physical memory. This is an indicator of application I/O.

Higher is better. A poor cache hit rate may indicate a memory shortage.

LogicalDisk Object

Avg. Disk Queue Length

A measure of the activity of each logical partition of the disk. An Avg. Disk Queue Length of 1.0 indicates that the logical disk was busy for the entire sample time. Busy time includes all processing time for a disk I/O request, including driver time and time in the queue, so values for a single logical disk may exceed 1.0.

Sustained high values over time indicate a possible disk bottleneck.

% Free Space

The ratio of the free space available on the logical disk to the total usable space provided by the selected logical disk drive.

Higher is better. Free space should not go below 10 percent, or disk performance will suffer. If the drive that SMS is installed on runs out of free space, SMS will stop all processing and SMS won't be able to send events warning that all processing has stopped.

Memory Object

Committed Bytes

The size of virtual memory that has been committed (rather than reserved). Committed memory must have disk storage available, or there must be enough memory available so that it doesn't need to use. Notice that this is an instantaneous count, not an average over the time interval.

Lower is better. If the value is consistently less than the amount of physical RAM, then additional RAM is not needed. If the value is consistently more than twice the amount of physical RAM, and the system is paging frequently, then more RAM may be needed.

Page Faults/sec

A count of the page faults in the microprocessor. A page fault occurs when a process refers to a virtual memory page that is not in its Working Set in main memory. A page fault will not cause the page to be retrieved from disk if that page is on the standby list, and already in main memory, or if it is in use by another process that shares the page.

Lower is better.

Pages/sec

The number of pages read from the disk or written to the disk to resolve memory references to pages that were not in memory at the time of the reference. This is the sum of pages input/sec and pages output/sec. This counter includes paging traffic on behalf of the system cache to access file data for applications. This is the primary counter to observe if you are concerned about excessive memory pressure (thrashing), and the excessive paging that can result.

Lower is better. If this counter is consistently high, memory is in short supply. Sustained paging degrades performance.

Pool Non-Paged Bytes

The number of bytes in the non-paged pool. The non-paged pool is a system memory area where space is acquired by operating system components as needed. Non-paged pool pages cannot be paged out to the paging file; they remain in main memory as long as they are allocated.

Lower is better. If this level approaches the amount of physical RAM, the system can stall.

Transition Faults/sec

The number of page faults resolved by recovering pages that were in transition, that is being written to disk at the time of the page fault. The pages were recovered without additional disk activity.

Lower is better. As the number of transition faults approaches the number of page faults, the applications running will approach a state where they produce little results other than thrashing the disk. You can add more RAM to reduce this problem.

Objects Object

Processes

An instantaneous count of the number of processes running. When charted with Processor: % ProcessorTime, it shows the effect on the microprocessor of adding and removing processes.

Paging File Object

%Usage Peak

The peak usage of the page file instance in percent.

Lower is better. If it is over 80 percent, increase the size of the paging file or add more RAM.

PhysicalDisk Object

Numbers are shown for an array as a group. The first disk shows numbers, the others show zeros. Note that you must run diskperf -y and restart the computer before you can use this counter. For Pentium-class computers, the impact of enabling these counters is negligible.

Avg. Disk Queue Length

A measure of the activity of the disk subsystem. It is the sum of Avg. Disk Queue Length for all logical partitions of the disk.

This is a good measure of disk activity when measuring multiple physical disks in a disk set.

%Disk Time

The percentage of elapsed time that the selected disk drive is busy servicing read or write requests.

Lower is better. Recommended range is 50% or below. Avoid averaging over 80 percent. This is a good counter to check to determine if the disk is acting as a system bottleneck. A high value may indicate the need for a faster disk, or it may indicate system configuration problems.

Disk Bytes/sec

The rate bytes are transferred to or from the disk during write or read operations.

Lower is better. The throughput for most disks is in the range of 1 to 4 MB per second. To get a feel for the upper limit for a specific disk, start several file copy operations from other physical disks, RAM, or the network. Keep in mind that reading and writing have different limits and that file size, block size, and other factors will effect disk throughput. The whole point to an array is to multiply the throughput by increasing the number of disks. If the throughput for a single disk is 3 MB per second, and 4 disks are used for an array, the total throughput should approach 12 MB per second. There is overhead with arrays that will prevent the actual throughput from reaching this point.

Disk Queue Length

The rate that bytes are transferred to or from the disk during write or read operations.

Lower is better. More than two is not recommended. This is two per disk, in an array, that divide the disk queue length by the number of disks.

Process Object

These are the key processes to monitor in an SMS environment:

  • Idle (unused system resources)
  • PERFMON
  • PREINST
  • SITEINS
  • SMS
  • SMSEXEC
  • SQLSERVER (version 4.x)
  • MSSQLSERVER (version 6.x)

For each process, you can monitor the following counters:

% Processor Time

The percentage of elapsed time when all the threads for a process are used by the microprocessor to execute instructions. An instruction is the basic unit of execution in a computer. A thread is the object that executes instructions. A process is the object created when a program is run. Code executed to handle certain hardware interrupts or trap conditions may be counted for this process.

Lower is better. If a single process is using close to 100 percent of the microprocessor time for extended periods, then it is causing a microprocessor bottleneck.

Private Bytes

The current number of bytes this process has allocated that cannot be shared with other processes.

Lower is better. If this number shows a steady upward climb, that could suggest a memory leak. Monitor this value over a period of several hours to be sure it is not a one time increase, as many processes will allocate a great deal of memory on startup.

Processor Object

% Interrupt Time

The percentage of elapsed time that the microprocessor spent handling hardware interrupts. When a hardware device interrupts the microprocessor, the interrupt handler manages the condition, usually by signaling I/O completion and possibly issuing another pending I/O request. Some of this work may be done in a deferred procedure call (DPC). However, time spent in DPCs is not counted as time in interrupts. Interrupts are executed in privileged mode, so this is a component of Processor: % Privileged Time. Use this counter to determine the source of excessive time for Privileged Mode.

Lower is better.

% Processor Time

Expressed as a percentage of the elapsed time that a microprocessor is busy executing a non-idle thread. It is viewed as the fraction of time spent doing productive work. Each microprocessor is assigned an idle thread in the idle process that consumes those unproductive microprocessor cycles not used by any other threads.

Lower is better. Recommended range is 50% or below. This value is a good indicator of the demand for and efficiency of a microprocessor.

Interrupts/sec

The number of device interrupts that the microprocessor is experiencing. A device interrupts the microprocessor when it has completed a task or when it requires attention. Normal thread execution is suspended during interrupts. An interrupt may cause the microprocessor to switch to another, higher priority thread. Clock interrupts are frequent and periodic and create a background of interrupt activity.

Lower is better. A high level indicates a type of microprocessor thrashing. On a Pentium computer, 500 interrupts per second might be normal. High can be as much as 1,000 interrupts per second.

Redirector Object

Bytes Total/sec

The rate at which the Redirector is processing data bytes. This includes all application and file data in addition to protocol information such as packet headers.

Lower is better.

Current Commands

Counts the number of requests to the Redirector that are currently queued. If this number is much larger than the number of network adapter cards installed in the computer, then the network(s) and/or the server(s) being accessed are a bottleneck.

Lower is better.

File Data Operations/sec

The rate at which the Redirector is processing data operations. One operation includes many bytes because each operation has overhead. You can determine the efficiency of this path by dividing the bytes per second by this counter to determine the average number of bytes transferred per operation.

Lower is better.

Network Errors/sec

Counts unexpected errors that generally indicate the Redirector and one or more servers are having communication difficulties. For example, an SMB (Server Manager Block) protocol error will generate a network error. This results in an entry in the system event log, so look there for details.

Lower is better.

Packets/sec

The rate at which the Redirector is processing data packets. One packet includes many bytes. You can determine the efficiency of this path by dividing the bytes per second by this counter to determine the average number of bytes transferred/packet. You can also divide this counter by operations per second to determine the average number of packets per operation, which is another measure of efficiency.

Lower is better.

Server Sessions Hung

Counts the number of active sessions that are timed out and unable to proceed due to a lack of response from the remote server.

Lower is better.

Server Object

Bytes Total/sec

The number of bytes the server has sent to and received from the network. This value provides an overall indication of the server's activities.

Lower is better.

Context Blocks Queued/sec

The rate that work context blocks had to be placed on the server's FSP queue to await server action.

Lower is better.

Pool Non-paged Bytes

The number of bytes of non-pageable computer memory that the server is currently using. Use this counter to determine usable values for maxnonpagedmemoryusage.

Lower is better.

Pool Non-paged Failures

The number of times allocations from non-paged pool has failed. Use this counter to determine if the computer's physical memory is too small.

Anything other than zero is not recommended.

Pool Non-paged Peak

The maximum number of bytes in a non-paged pool that the server has had in use at any point. Use this counter to determine how much physical memory the computer should have.

Lower is better, and should leave a buffer of available RAM. Depending on the applications, additional space might be needed to page data and code.

Pool Paged Bytes

The number of bytes of pageable computer memory that the server is currently using. Helps determine good values for maxpagedmemoryusage.

Lower is better.

Pool Paged Failures

The number of times that allocations from the paged pool have failed. Use this counter to determine if the computer's pagefile physical memory is too small.

Anything other than zero is not recommended.

Pool Paged Peak

The maximum number of bytes of paged pool that the server has allocated. Use this counter to determine the proper sizes for the page file(s) and physical memory.

Lower is better. The total for RAM and page file should be at least 20 percent larger than this number.

Sessions Errored Out

The number of sessions that have been closed due to unexpected error conditions. Use this counter to determine how frequently network problems are causing dropped sessions on the server.

Lower is better.

Server Work Queues Object

Bytes Transferred/sec

The rate at which the server is sending and receiving bytes with the network clients on this CPU. Use this counter to determine how busy the server is.

Lower is better.

Queue Length

The current length of the server work queue for this CPU. A sustained queue length greater than four can indicate microprocessor congestion. This is an instantaneous count, not an average over time.

Lower is better.

Total Bytes/sec

The rate at which the server is reading and writing data to and from the files for the clients on this CPU. Use this counter to determine how busy the server is.

Lower is better.

Total Operations/sec

The rate at which the server is performing file read and file write operations for the clients on this CPU. This value will always be zero (0) in the Blocking Queue instance. Use this counter to determine how busy the server is.

Lower is better.

Work Item Shortages

Each request from a client is represented on the server as a work item, and the server maintains a pool of available work items per CPU to speed processing. A sustained value greater than zero indicates the need to increase MaxWorkItems for the Server service. This value will always be zero (0) in the Blocking Queue instance.

Anything other than zero is not recommended.

SQLServer Object

Cache Hit Ratio

The percentage of time that a requested data page was found in the data cache (instead of being read from disk).

Higher is better. 99% is desirable. If the percentage consistently averages below 97%, you should increase the amount of memory allocated to SQL Server.

I/O - Outstanding Reads

The number of pending physical reads.

Averaging more than two is not recommended.

I/O - Outstanding Writes

The number of pending physical writes.

Averaging more than two is not recommended.

Max Tempdb Space Used (MB)

The maximum amount of tempdb RAM used (in MB).

Max Users Connected

The maximum number of user connections used.

NET - Command Queue Length

The number of client requests that are waiting to be handled by the SQL Server working threads.

Averaging more than two is not recommended.

User Connections

The number of open user connections.

Lower is better. This number should always be at least 10 lower than the maximum limit set in SQL Server. Running out can cause SMS to stall, and also prevents remote access.

SQLServer-Locks Object

Total Locks

A count of all locks being used by SQL Server.

Lower is better. This number should be lower than the maximum limit set in SQL Server.

SQLServer-Log Object

Log Space Used (%)

The amount of space allocated to the transaction log.

Lower is better. If the log space used exceeds 60 percent, the logical log device needs to be increased in size. This should be monitored for both the tempdb and the SMS database log device.

System Object

% Total Interrupt Time

The sum of % Interrupt Time of all microprocessors divided by the number of microprocessors in the system.

Lower is better.

% Total Processor Time

Include this counter to monitor systems with multiple microprocessors. It combines the average microprocessor usage of all microprocessors into a single counter. It can be viewed as the fraction of time spent doing productive work. Each microprocessor is assigned an idle thread in the idle process, which consumes unproductive microprocessor cycles not used by any other threads.

Lower is better.

Processor Queue Length

The instantaneous length of the microprocessor queue in units of threads. This counter is always 0 unless you are also monitoring a thread counter. All microprocessors use a single queue for threads to wait for microprocessor cycles. This length does not include the threads currently running. A sustained microprocessor queue length greater than two generally indicates microprocessor congestion. This is an instantaneous count, not an average over the time interval.

Averaging more than two is not recommended.

System Up Time

The total time (in seconds) that the computer has been operational since it was last started. Use this counter to determine how often to restart the server.

Total Interrupts/sec

The rate at which the computer is receiving and servicing hardware interrupts. The devices that generate interrupts are the system timer, the mouse, data communication lines, network interface cards, and other peripheral devices. This counter provides an indication of how busy these devices are on a computer-wide basis.

Lower is better.

Thread Object

The thread object is typically used during debugging when looking for the source of a problem, and particularly when tracking SMSEXEC thread components.

% Processor Time

Threads are the components of a process that execute its code on the microprocessor. This counter indicates which threads are getting microprocessor time.

Lower is better.

Elapsed Time

The total elapsed time (in seconds) that this thread has been running.

Lower is better. Some threads may need several minutes to initialize. The longer the thread has been running, the greater the chance for a memory leak, or for corruption to occur.

ID Process

The unique identifier of this process. ID process numbers are reused, so they only identify a process for the lifetime of that process.

ID Thread

The unique identifier of this thread. ID thread numbers are reused, so they only identify a thread for the lifetime of that thread.

Priority Base

The current base priority of this thread. The system may raise the thread's dynamic priority above the base priority if the thread is handling user input, or lower it towards the base priority if the thread becomes compute bound.

Priority Current

The current dynamic priority of this thread. The system may raise the thread's dynamic priority above the base priority if the thread is handling user input, or lower it towards the base priority if the thread becomes compute bound.

Thread State

The current state of the thread:

Value | State | Meaning
0 | Initialized | Thread has just initialized.
1 | Ready | Thread is waiting for a microprocessor because none are free.
2 | Running | Thread is using a microprocessor.
3 | Standby | Thread is about to use a microprocessor.
4 | Terminated | Thread has been terminated.
5 | Wait | Thread is waiting for a peripheral operation to complete or a resource to become free.
6 | Transition | Thread is waiting for a resource in order to run (such as waiting for its execution stack to be paged in from disk).
7 | Unknown | Thread is in an unknown state.

Thread Wait Reason

This counter only applies when the thread is in Wait state. It is:

Value | The thread is waiting for
0 or 7 | Executive
1 or 8 | Free page
2 or 9 | Page in
3 or 10 | Pool allocation
4 or 11 | Execution delay
5 or 12 | Suspended condition
6 or 13 | User request
14 | Event pair high
15 | Event pair low
16 | LPC receive
17 | LPC reply
18 | Virtual memory
19 | Page out

Network Performance Objects

You should also include counters to monitor network throughput. The counters you choose depend upon your network protocol and whether the computer is primarily a client, a server, or both. NetBios: Bytes Total/sec for NWLink and Network Interface: Bytes Total/sec for TCPIP/SNMP are good overview counters.

Locating Bottlenecks in the SMS Executive

The SMS Executive is an SMS service that controls multiple SMS components. Because these components all run as threads under SMSEXEC, it can be quite difficult to determine what each component is doing. This section explains how to determine which SMS component thread is causing a bottleneck. The section assumes a problem with CPU utilization, but the technique discussed can be applied to other tuning concerns as well.

To determine if you have a CPU bottleneck, you might start by monitoring the Process: %Processor Time for the Idle process. If this counter is less than about 15 percent, you probably have a CPU bottleneck. Monitor the other system processes to determine which one is using the most CPU time. If the bottleneck is in SMSEXEC, use the following procedure to determine which thread in SMSEXEC is causing the problem:

1. For all instances of SMSEXEC, add counters for THREAD: %Processor Time and THREAD: ID Thread.

2. Determine which thread is taking the most processor time. Note the instance number (decimal) reported in the Instance column in the chart.

3. Determine which ID Thread counter has the same instance number. Note the value that is reported in decimal and convert this number to hexadecimal.

4. Start the Registry Editor (regedt32).

5. Locate the thread ID that matches the ID Thread counter under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\COMPONENTS \SMS_EXECUTIVE\Threads. This thread is taking the CPU time.

6. If the ID Thread is a SQL Server thread, consider turning on SQL Server tracing. This will provide a log of the exact SQL statement that is being run. SQL Server tracing is set in following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\TRACING SQLEnabledc

Use 1 to enable tracing and 0 to disable tracing. To activate this change, stop and restart the SMS Executive.

Note

If you suspect that a certain SMS component is causing performance problems, and you want to see the log for the component, you can run the SMSTRACE or the TRACER program against the log file for the component. These programs display the component logs in real-time. The SMSTRACE program has a graphical user-interface and is therefore preferred. For more information, see the SMSTOOLS.HLP file.

If the interface to SQL Server is causing the bottleneck, you can use the SQLTRACE utility provided with SQL Server to monitor SQL Server activity. The SQLTRACE utility is located in the SQL Server program group.


Task Manager

Task Manager is a new tool introduced with Windows NT 4.0. It lets you monitor active applications and processes on your computer, and start and stop them. It also has basic performance-monitoring capabilities.

Task Manager offers the following features:

  • It displays running applications and processes, including 16-bit processes.
  • It displays the most commonly used performance measures for processes, including microprocessor time, main memory size, virtual memory size, page faults, base priority, and number of threads.
  • It displays line graphs and instantaneous values of microprocessor and memory use for the computer.
  • It lets you set microprocessor affinity for a process, change the base priority class of a process and activate a debugger, if you have one.

Task Manager gets its data from the same functions used by Performance Monitor. However, it calls these functions directly, bypassing the Performance Library and the registry. Thus, it cannot log data to a file and it cannot monitor remote computers. However, it is a useful tool for quick checks of basic counters and for training users to monitor their own computer.


Starting Task Manager

Task Manager is integrated into Windows NT 4.0 and does not need to be installed separately. This section explains how to use Task Manager as a performance monitoring tool. For more general information, see Task Manager Help or the Windows NT documentation.

To start Task Manager, use any of these methods:

  • Press ctrl+shift+esc.
  • Use the right mouse button to click the Task Bar, then click Task Manager.
  • Press ctrl+alt+delete, then click Task Manager.

You can also start Task Manager from the command prompt or the Run command, and you can create a shortcut to Taskmgr.exe.

The following window is displayed when you start the Task Manager:

Task Manager has three tabs, but the status bar always displays the total number of processes, CPU use, and virtual memory use for the system. When Task Manager is running, an accurate miniature CPU usage gauge appears on the taskbar on the end opposite the Start button.


Monitoring Processes with Task Manager

Select the Task Manager Processes tab to see a list of running processes and measures of their performance. The Task Manager process table includes all processes that run in their own address space, including all applications and system services. From the Options menu, choose Show 16-bit Tasks to include those in the display.

Note

Task Manager displays its values in kilobytes, which are units of 1024 bytes. Performance Monitor displays the full number values. When comparing Performance Monitor and Task Manager values, multiply Task Manager values by 1024 (and drop the K). For example, in the following illustration, Task Manager shows the PERFMON.EXE process using 28K bytes of memory. In Performance Monitor, this value would be displayed as 28,672 bytes.

From the View menu, choose Select Columns to add to or remove performance measures from the display. The following table briefly describes the measures and their Performance Monitor counterparts, if any.

Process measure

Description

Performance Monitor Process counter

Image Name

Name of the process.

The process name in the Instances box.

PID (Process Identifier)

Numerical ID assigned to the process while it runs.

ID Process.

CPU Usage

The percentage of time the threads of the process used the microprocessor since the last update.

%Processor Time.

CPU Time

The total microprocessor time used by the process since it was started, in seconds.

None.

Memory Usage

The amount of main memory used by the process, in kilobytes.

Working Set.

Memory Usage Delta

The change in memory use since the last update, in kilobytes. Unlike Performance Monitor, Task Manager displays negative values.

None.

Page Faults

The number of times data had to be retrieved from disk for this process because it was not found in memory. This value is accumulated from the time the process is started.

None.

Page faults/sec is the rate of page faults over time.

Page Faults Delta

The change in the number of page faults since the last update.

None.

Virtual Memory Size

Size of the process's share of the paging file, in kilobytes.

Page File Bytes.

Paged Pool

Amount of the paged pool (user memory) used by the process, in kilobytes.

The paged pool is virtual memory available to be paged to disk. It includes all of user memory and a portion of system memory.

Pool Paged Bytes.

Nonpaged Pool

Amount of the non-paged pool (system memory) used by the process, in kilobytes.

The non-paged pool is operating system memory, which is never paged to disk.

Pool Nonpaged Bytes.

Base Priority

The base priority of the process, which determines the order in which its threads are scheduled for the microprocessor.

The base priority is set by the process code, not the operating system. The operating system sets and changes the dynamic priorities of threads in the process within the range of the base.

Use Task Manager to change the base priority of processes.

Priority Base.

Handle Count

The number of object handles in the process's object table.

Handle Count.

Thread Count

The number of threads running in the process.

Thread Count.

Setting the Update Speed

You can control the rate at which Task Manager updates its counts. This will reduce Task Manager overhead, but might miss some data. You can force an update at any time by choosing Refresh Now from the View menu or by pressing f5.

Task Manager Update Speed options:

Option | Description
High | Updates every half-second.
Normal | Updates once per second.
Low | Updates every four seconds.
Paused | Does not update automatically. Press F5 to update.


Using Task Manager to Monitor System Performance

Select the Task Manager Performance tab to see a dynamic overview of system performance, including a graph and numeric display of microprocessor and memory usage.

To graph the percentage of microprocessor time in privileged or kernel mode, from the View menu, choose Show Kernel Times. This is a measure of the time applications are using operating system services. The remaining time, known as user mode, is spent running threads within the application code.

If you are monitoring a computer with multiple microprocessors, from the View menu choose CPU History, and then choose to graph the non-idle time of each microprocessor in a single graph or in separate graphs.

The following table briefly describes the counts on the Performance tab and their Performance Monitor counterparts, if any.

Task Manager counts | Description | Performance Monitor counters
CPU Usage | The percentage of time the microprocessor is running a thread other than the Idle thread. | Processor: % Processor Time and System: % Total Processor Time
MEM Usage | The amount of virtual memory used, in kilobytes. | Memory: Committed bytes
Total Handles | The number of object handles in the tables of all processes. | Process: Handle Count: _Total
Total Threads | The number of running threads, including one Idle thread per microprocessor. | Process: Thread Count: _Total
Total Processes | The number of active processes, including the Idle process. | Object: Processes is the same, but excludes the Idle process
Physical Memory: Total | Amount of physical, RAM installed in the computer, in kilobytes. | None
Physical Memory: Available | Amount of physical memory available to processes, in kilobytes. It includes zeroed, free, and standby memory. | Memory: Available Bytes
Physical Memory: File Cache | Amount of physical memory released to the file cache on demand, in kilobytes. | Memory: Cache Bytes
Commit Charge: Total | Size of virtual memory in use by all processes, in kilobytes. | Memory: Committed Bytes
Commit Charge: Limit | Amount of virtual memory, in kilobytes, that can be committed to all processes without enlarging the paging file. | Memory: Commit Limit
Commit Charge: Peak | The maximum amount of virtual memory used in the session, in kilobytes. The commit peak can exceed the commit limit if virtual memory is expanded. | None
Kernel Memory: Total | Sum of paged and non-paged kernel memory, in kilobytes. Kernel refers to memory available to operating system components running in highly privileged kernel mode. | None (Sum of Pool Paged Bytes and Pool Nonpaged Bytes)
Kernel Memory: Paged | Size of the paged pool allocated to the operating system, in kilobytes. The paged pool is an area of operating system memory that can be paged to disk as applications demand more memory. | Memory: Pool Paged Bytes
Kernel Memory: Nonpaged | Size of the non-paged pool allocated to the operating system, in kilobytes. The non-paged pool is the part of operating system memory that remains in physical memory as long as it is allocated. | Memory: Pool Nonpaged Bytes


Tuning Tips

Once you have determined that your SMS system has a bottleneck, you need to tune the computer so that the bottleneck does not impair system performance. You can do this by decreasing the load on the component, or by increasing the capacity on the component. For instance, if you find that the CPU is the bottleneck, you can reduce the number of applications running on the computer (thus reducing the load on the CPU), or you can add faster or multiple CPUs (thus increasing the processing capacity).

The following sections contain information about things you can do to prevent or fix bottlenecks once you have identified them.


Perform the Recommended Maintenance Tasks

Chapter 15 in the SMS version 1.2 Administrator's Guide includes a section called "Common Administrative Tasks." This section outlines the tasks that you should perform on a regular basis to keep the SMS system, services, and database functioning efficiently.


Ensure Computers Have Adequate Capacity

Capacity planning is the process of ensuring that a system has enough resources to perform optimally. Ideally, capacity planning should be done before you implement SMS, however it is often a good idea to review your planning assumptions after you have deployed SMS. To review the guidelines for capacity planning, see the SMS version 1.2 Concepts and Planning, Chapters 10 and 11.

Capacity planning guidelines generally focus on computer CPU, disk, memory, and networking capabilities. The following guidelines should be observed for SMS site servers:

A fast CPU is required.

The site server requires a fast Pentium, Alpha, or MIPS CPU. In certain cases, multiple CPUs are recommended.

A large, fast, NTFS disk is required.

The site server should have a fast disk formatted as NTFS. Multiple drives or drive arrays are recommended. The disks should have at least 500 MB free; 1 GB free space is recommended. If possible, each major application (Windows NT Server, SMS, SQL Server) should have its own physical disk.

At least 24 MB memory is required.

A site server running only Windows NT Server and SMS should be configured with at least 24 MB. A site server running SQL Server in addition to Windows NT Server and SMS should be configured with at least 32 MB. Additional memory should be allocated to other major applications (such as Microsoft SNA Server or the Windows NT Server Services for Macintosh). In certain cases, up to double the required amount of memory is recommended.

A fast network interface is required.

The site server must communicate with many other servers (some in its own site, some in remote sites).


Optimize Site Design

You should examine the amount of network traffic within each SMS site, and between SMS sites, because the structure of the SMS hierarchy has a significant impact on performance. Poor system performance or excessive network traffic may indicate site design problems. Some possible site design problems are:

  • Inadequate bandwidth between sites.
  • A single SMS site that should be multiple sites.
  • Multiple SMS sites that might perform better as a single site.
  • A single domain (perhaps split across multiple sites) that should be split into multiple domains.
  • Too many SMS domains or SMS logon servers in a site.
  • Too many secondary sites under a primary site.
  • Too many or too few package distribution servers per site.
  • Clients not reliably mapping to a specific site or SMS domain.
  • Clients unable to reliably connect to their SMS logon servers or distribution servers.


Optimize SQL Server Performance

Many SMS services and components make extensive use of SQL Server. In order for SMS to perform well, the computer running SQL Server must be configured for optimum performance. In addition, there should be a fast interface between the SQL Server and the services and components using the SQL Server.

Each instance of the SMS Administrator uses SQL Server. In addition, the following SMS services use SQL Server:

  • SMS Executive
  • Hierarchy Manager

The following threads (running in the SMS Executive) use SQL Server:

  • Alerter
  • Applications Manager
  • Data Loader
  • Scheduler
  • SNMP Trap Filter and Receiver


Adjust Server Load

If any SMS servers are performing poorly, see if they are overloaded with other tasks. To do this, determine all other services running on the server, such as logon processing, application sharing, file and print, and so on. Check to see if any of these services can be moved to other servers.

If SMS servers are running SQL Server, serving as package source or package distribution servers, or running SMS sender components, consider moving these functions to other servers. Note that, by default, the site server is used as a distribution server; you can select the distribution servers to be used in a site in the Site Properties dialog box.


Optimize Site Properties Settings

You should optimize the site properties settings for all SMS sites. Site performance is most affected by the service response interval, which is set in the Site Properties dialog box. Setting it to Very Fast causes services to poll more frequently, and increases the load on the SMS system. Setting the service response interval to Slow retards service polling, and causes a much lighter system load. You should set the service response interval so that it runs as often as needed, without overloading the system.

Other site properties settings that can affect system performance are:

  • Setting the inventory frequency too high (default is once every seven days).
  • Setting the Package Command Manager (PCM) polling interval too high (default is once every 60 minutes).
  • Running inventory on clients that use a slow network.


Plan and Monitor Jobs Efficiently

You can use the flexibility built into SMS to schedule and manage jobs efficiently. Schedule jobs to occur during off-hours or on weekends. Use outbox scheduling to ensure data is not sent between sites during busy times. Do not force mandatory installations for large groups at peak times, or even at the same time. Do not recompress or resend packages that have been sent but were not modified.


Optimize Use of Logging

Logging provides very useful troubleshooting data, but significantly degrades system performance. You can use the SMS Service Manager to enable or disable tracing for each SMS service. If you enable logging, you should also use the SMS Service Manager to set the trace file log size. Be sure the file is large enough to collect at least 24 hours worth of data in each log file.

SMS allows you to enable logging for SQL Server as well as for the SMS services. To enable SMS logging for SQL Server, use the following registry key to change the values for SQLEnabled and Enabled from 0 to 1:

HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\SMS\TRACING

You must restart all SMS services and tools for this change to take effect. SQL Server logging is extremely resource-intensive. In general, you should not enable SQL Server logging unless you are actively working on a SQL Server problem.


Control User Group MIF File Collection

If you have a large number of user groups, especially in trusted domains, make sure your site is not generating too many user group MIF files. If you detect a performance problem relating to user group MIF files, use the Set Global User Groups (SETGUG.EXE) tool to turn off or slow down the user group MIF file interval.

SMS collects all global user groups for all SMS domains in each site. User groups are reported at pre-set intervals, as well as each time the Site Configuration Manager starts, even if there are no status changes. User group MIF files include information for every user group that SMS finds in the site—in every SMS domain, and in all trusted domains. In a large SMS hierarchy, especially one with many trusted domains, each user group can be reported many times (once for each site that has access to it through a trust relationship).

User groups are mainly used with program groups, although they can be used with alerts and queries. In most cases, you can reduce the collection frequency. This reduces the load at all sites, and on every server that forwards MIF files.

If you have many MIF files backing up in the DELTAMIF.COL directory, look at some of the bigger files. If they are bigger than 50K and are user group MIF files, you should probably reduce the frequency for user group MIF file collection.


Optimize File Collection and Software Inventory

For file collection, SMS collects all versions of a file. For instance, if you enable file collection and specify CONFIG.SYS, SMS collects every copy of CONFIG.SYS on each client.

Because SMS does not delete collected files, you must do this manually with the SMS Database Manager. For more information, see "Remove Unused Files from the Site Server" later in this chapter.

If you enable software inventory, avoid creating too many software inventory rules. Monitor the time SMS inventory takes to run on typical clients in your sites. If too much time is devoted to software inventory, you can:

  • Remove the package rules.
  • Disable software inventory.
  • Use Software Audit instead of software inventory. Audits are run as Package Command Manager jobs, and can be scheduled to run at a specified time. Software Audit can also be used to target specific computers.


Remove Unused Files from the Site Server

In some cases, you can significantly increase the performance of an SMS site just by removing old, unused files from the site server. Many SMS processes scan all files in a directory each time the directory is accessed. If there are many unused files on a site server, those files will waste disk space and bog down the SMS services. Removing these old files will increase overall performance (stop the SMS services on the site server before removing the files).

You should check for unused files in the following directories:

  • SITE.SRV\INVENTRY.BOX\HISTORY

When records are deleted from the database, the history files in this directory are not deleted. These files are updated each time an inventory record is updates, so if a file is older than several months, the file is probably not being used any more. Search for files with old dates and determine if the files correspond to current records in the inventory; if not, delete the files.

  • SITE.SRV\MAINCFG.BOX\PCMDOM.BOX

Each computer in a site has a package instruction file in this directory (if a package has ever been sent to the computer). These files are not deleted when a computer is deleted from the database. After a simple maintenance job is sent to all computers in a site, any instruction files dated before that job are for computers no longer in use by that database. Sort these files by date and delete the old instruction files.

After this is done, the same task will need to be done on each SMS logon server in the LOGON.SRV\PCMINS.BOX directory. Delete the files on the logon servers after you have deleted the files on the site server. This ensures that old instructions files are not replicated to the logon servers as you work.

  • SITE.SRV\DATALOAD.BOX\FILES.COL

When you enable file collection in SMS, the collected files are placed in this directory. These files should be deleted with the SMS Database Manager. For more information, see the SMS version 1.2 Administrator's Guide, Chapter 15.


Prevent Resyncs

Resyncs occur when inventory information reported to the database does not match information already in the database. The Inventory Data Loader creates a system job to send a resync request to the specified computer. The resync command is written to the master inventory command file (RESYNC.CFG) for the computer's SMS domain. This file is then replicated to all SMS logon servers in the SMS domain. When the computer reads the resync request, it generates a full inventory MIF file, which is sent to the database.

Use SMS Database Manager to prevent resyncs by periodically checking for duplicate computers in the database. Delete older duplicates, and fix any problems that may cause duplicate computers to appear. Do not delete all duplicates because this will cause even more resyncs.

Resyncs send system jobs down the hierarchy, while resync MIF files and events MIF files are sent up the hierarchy. This can overload SMS, especially in a large SMS hierarchy. In addition, the RESYNC.CFG file can grow quite large, which can slow down log ons. If you experience a lot of resyncs in a site, and the resync file grows larger than 50K, you can delete the resync file. The source for the RESYNC.CFG is:

SITE.SRV\MAINCFG.BOX\INVDOpSM.BOX\DOMAIN_X.000\RESYNC.CFG

The next time a resync occurs, SMS will create a new resync file.


Optimize Alerts

Do not set up too many alerts, especially those running complex queries, and do not run alerts too frequently. Alerts that run complex queries can be quite SQL Server intensive.


Chapter 7 - Troubleshooting

Microsoft Systems Management Server (SMS) provides a number of techniques for monitoring and troubleshooting the system. The primary troubleshooting techniques are:

  • Using the tools provided in the Microsoft BackOffice Resource Kit to actively troubleshoot SMS services and applications.
  • Using the tools (such as remote control and Network Monitor) provided with SMS version 1.2 to actively troubleshoot computers on the network.
  • Checking the status of SMS jobs in the Jobs windows of the SMS Administrator.
  • Checking the events in the Events window and in the Windows NT event log.
  • Checking the status of the files that are created, modified, copied, and deleted during normal system operation.
  • Checking the trace logs for the SMS services and components.

Because jobs are the primary way in which administrators accomplish tasks in SMS, this chapter focuses almost exclusively on troubleshooting jobs. However, all of the information and techniques described in this chapter also apply to troubleshooting other system o`perations, such as client installation or inventory collection.

For more information about | See
Using the tools provided with this resource kit to troubleshoot SMS. | The online documentation (SMSTOOLS.HLP) provided with the Microsoft BackOffice Resource Kit.
Using the tools provided in SMS to troubleshoot the system. | SMS version 1.2 Concepts and Planning, Chapter 7.
Using job status to troubleshoot the system. | "Monitoring Jobs" later in this chapter.
Using events to troubleshoot the system. | "Using Events" later in this chapter.
Using system flow to troubleshoot the system. | "Using System Flow" later in this chapter.
Using the trace logs to troubleshoot the system. | "Using Trace Logs" later in this chapter.


Monitoring Jobs

After creating a job, you can view the progress and status of the job. For each job, you can view its status at each target site and at each target computer in each target site. Job status can be used to monitor and troubleshoot jobs.


Overall Job Status

In the Jobs window, each job displays its overall status. The overall status is also displayed in the Job Status dialog box.

To view the overall status for a job, in the SMS Administrator, open the Jobs window. The Jobs window displays an overview of the current status of each job for all target sites.

There are seven Overall Status states:

Pending

Indicates that the job has not started and that the Scheduler is waiting to activate the job. When a job has this Overall Status, you can delete the job and prevent it from starting. You can also modify the job's properties before it starts.

Active

Indicates that the Scheduler has started the job and that SMS is currently carrying out the job without errors. The job may be complete or may still be in progress at the target sites or computers.

Retrying

Indicates that the job has failed at some target sites or target computers; however, SMS is still attempting to complete the job at those sites or computers. The job may be complete or may still be in progress at other target sites or computers.

Complete

Indicates that the job successfully completed its tasks on all target computers at all target sites. When a job has this Overall Status, you can delete the job from the Jobs window because the system does no further processing on the job.

For Run Command On Workstation Jobs, Overall Status is Complete when every client targeted in the job has successfully received the package and run the job. For Share Package On Server jobs, Overall Status is complete when the package has been successfully distributed to all specified distribution servers.

Canceling

Indicates that the job is being canceled at all target sites. When a job has this Overall Status, you cannot delete the job from the Jobs window.

Canceled

Indicates that the job was successfully canceled at all target sites. When a job has this Overall Status, you can delete the job from the Jobs window because SMS does no further processing on the job.

Failed

Indicates that the job has failed at some or all target sites or target computers and that SMS has stopped trying to complete the job. The job may have completed successfully at some target sites or computers. You can note the job ID and check the event log to determine why the job failed.


Job Status

The job status dialog box shows the progress of the job at all target sites.

To view job status at each target site

1. In the SMS Administrator, open the Jobs window, select the job, and from the File menu, choose Properties.

2. In the Job Properties dialog box, choose Status.

The Job Status dialog box appears.

For each target site, Job Status displays an Overall Status, a Sending Status, a Working Status, and a Cancel Status. You can use the detailed status states to help troubleshoot jobs. Overall Status is described in "Overall Job Status" earlier in this chapter. The other three types of job status are described in the following sections.

Sending Status

For each target site, the Sending Status indicates the status for sending the job's package and instructions to the target site. There are seven Sending Status states:

None

Indicates that a sender has not processed the job's send request (the Scheduler has not created a *.SRQ file yet).

Pending

Indicates that the send request for the job has been placed in a sender outbox; however, the sender has not started to send the job package and instructions to the target site. The sender may not have detected the send request for the job yet. It is also possible that the sender has started or even finished sending, but that the Scheduler has not yet processed the sender feedback.

Active

Indicates that a sender is in the process of sending the job package and instructions to the target site (without errors) — but has not completed.

Retrying

Indicates that the sender has failed at an attempt to send the job to the target site; however, the sender is still attempting to send the job to the site. You can note the job ID and check the event log to determine why the job failed.

Complete

Indicates that the sender successfully sent the job package and instructions to the target site.

Canceled

Indicates that the job was successfully canceled before it was sent to thetarget site.

Failed

Indicates that the sender has failed to send the job to the target sites and that it has stopped trying to send the job to the site.

Working Status

For each target site, the Working Status indicates the job's progress at the target site. There are six Working Status states:

Pending

Indicates that the site has not yet received the job package and instructions.

Active

Indicates that the site has received the package and is in the process of carrying out the job at the site (without errors) — but has not completed.

Retrying

Indicates that the job has failed at one or more target computers in the site; however, the site components are still attempting to complete the job on the target computers.

Complete

Indicates that the job successfully completed on all target computers in the site.

Canceled

Indicates that the job was successfully canceled at all computers in the site.

Failed

Indicates that the job has failed at some or all target computers in the site and that the site components have stopped trying to complete the job. The job may have completed successfully at some target computers. You can note the job ID and check the event log to determine why the job failed.

Cancel Status

For each target site, the Cancel Status indicates how SMS has progressed in canceling the job. This status defaults to none and does not change unless you explicitly cancel the job. There are six Cancel Status states:

None

Indicates that the job has not been canceled.

Pending

Indicates that the site has not received the instructions to cancel the job yet.

Active

Indicates that the site has received the instructions to cancel the job and is in the process of canceling the job at the site (without errors) — but has not completed the cancellation.

Retrying

Indicates that the system has failed to cancel the job on some target computers at the site; however, the site components are still attempting to cancel the job on those target computers.

Complete

Indicates that the job was successfully canceled on all target computers in the site.

Failed

Indicates that the system has failed to cancel the job on some target computers in the site and that the site components have stopped trying to cancel the job. The job may have completed successfully on some target computers. You can note the job ID and check the event log to determine why the job failed.


Job Status Details

Using the Job Status Details dialog box, you can view a job's status for all target computers in an individual target site.

To view a job's status for all the target computers in a target site

1. In the SMS Administrator, open the Jobs window, select the job, and from the File menu, choose Properties. In the Job Properties dialog box, choose Status.

The Job Status dialog box for the job appears.

2. In the box, select the site whose target computers you want to view.

3. Choose Details.

The Job Status Details dialog box appears.

For each target computer, Job Status Details displays the following information:

Type

There are four types of details:

Arrival

Indicates that the package instructions have been received by the destination site.

Workstation

Specifies the target computer for the job's package command (for Run Command On Workstation jobs only).

Server

Specifies the distribution server where the package source directory is installed and made available to the target clients.

Completion

Specifies that the package has been received by all specified distribution servers.

Status

Provides the job status for the target computer. There are seven types of status:

Pending

Indicates that the computer has not yet received the job instructions.

Active

Indicates that the computer has received the job instructions and is in the process of carrying out the job — but has not completed.

Retrying

Indicates that the job has failed at the computer; however, the site components are still attempting to complete the job on the target computer.

Complete

Indicates that the job successfully completed on the computer. For a Run Command On Workstation job, this status indicates that the package command line successfully completed on the client.

Canceled

Indicates that the job was successfully canceled on the computer.

None

For a Run Command On Workstation job, this status indicates that no success or failure has been reported yet (the job has not been run).

Failed

Indicates that the job has failed on the computer and that the site components have stopped trying to complete the job. For a Run Command On Workstation job, this status indicates that the package command line may have failed on the client.

Detail

For a Run Command On Workstation job, the Detail field contains the SMS domain name and the SMS ID for the target computer.

For a Share Package On Server job, Detail contains either an arrival notification string (for example, "JOB ARRIVAL/COMPLETE 11/05/96") or the name of the distribution server.

For a Remove Package From Server job, Detail contains an arrival notification string.


Common Causes for Job Problems

SMS is designed so that a Run Command On Workstations job does not show a status of complete unless all possible target computers have run the package command. Because many Run Command On Workstations jobs are optional, and are distributed to a large number of computers, these jobs typically never complete. This does not indicate that an error has occurred. It just means that not all target computers have run the command.

The following sections describe some other common reasons why jobs might show a failed or incomplete status.


Scheduler Problems

The following are some common reasons why the Scheduler might not begin processing a job:

The Scheduler is sleeping.

The Scheduler runs on a polling interval. When you create a job, the Scheduler won't begin processing the job until its next polling cycle. The frequency of polling cycles is determined by the Service Response speed set in the Site Properties dialog box. Increasing the Service Response speed to a higher frequency might improve the Scheduler processing time.

The Scheduler is busy.

The Scheduler may not get to a job immediately upon beginning its polling cycle. This is because the Scheduler performs many tasks, and some of the tasks (such as compressing packages) may take a great deal of time. Since the Scheduler is single-threaded, it cannot activate any jobs while performing these tasks.

The scheduled job start time has not yet arrived.

When the Scheduler runs, it compares the date and time specified by Start After with the current time on the computer running SQL Server (not on the site server). The Scheduler will not start the job until the time on the SQL Server matches the job Start After time.

The Scheduler cannot access the SQL Server.

When you create a job, the job details are stored in the SQL Server database. In order to activate a job, the Scheduler must be able to access the database. If the SQL Server is down, or the Scheduler cannot access the computer running the database, then the Scheduler will not start the job.

The Scheduler is not running.

Under normal circumstances, the Scheduler should always be running on the site server (or on a helper server). The Scheduler is a component in the SMS Executive. You (or another administrator) can stop the SMS Executive, or even the Scheduler component itself (although this is not recommended). If you think that someone may have stopped the SMS Executive, use the SMS Service Manager to check that the SMS Executive is running. To verify that the Scheduler is running, look at the last entry in the Scheduler log file (SMS\LOGS\SCHED.LOG). The time stamp on the last entry should be fairly recent (minutes to hours old, depending on how fast the services are running and what the Scheduler is doing). If the Scheduler is not running, use the SMS Service Manager to start it.

The following are some common reasons why the Scheduler might not complete processing a job:

Scheduler cannot access the source directory.

This error will occur if the Scheduler does not have permission to access the package source directory. The Scheduler uses the SMS Service Account to access the package.

Source directory does not exist or does not contain any files.

This error will occur when the package source directory does not exist or does not contain any files. You must create the package source directory prior to creating the job, and the directory must contain at least one file.

Incorrect path specified.

If you use drive letters when specifying the location of the package source, you must specify the path relative to the computer running the Scheduler. For instance, if you use a specification such as D:\EXCEL, this is interpreted as drive D of the computer that the Scheduler is running on, not drive D of the computer running the SMS Administrator. Also remember, if `you move Scheduler to a helper server, the path means drive D on the helper server.

Site server is out of disk space.

The Scheduler needs to make a compressed copy of the package to send. The compressed version of the package is always created on the root of the SMS installation drive. This cannot be changed. If the drive does not have enough disk space for the compressed package, the job will fail. You can verify that the package has been compressed by looking for it in the SMS\SITE.SRV\SENDER.BOX\TOSEND directory. The compressed package file name uses the package ID (not the job ID).

Sender outbox closed.

If you used the Site Properties dialog box to close a sender outbox, the Scheduler will not assign the job to a sender until the outbox is open.

Addresses aren't defined for the target site.

If any of the target sites for a job do not have an address defined in SMS, the Scheduler will cause the job to fail.


Sender Problems

The following are some common reasons why a sender might not complete processing a job:

Maximum number of sends already in progress.

By default, no more than five jobs can be sent by a single sender, and no more than three jobs can be simultaneously sent to a single site. You can change these defaults using the SMS Sender Manager. For more information, see the SMS version 1.2 Administrator's Guide.

A higher priority job is activated.

SMS gives priority to jobs with the highest priority specified in the Job Schedule dialog box. For instance, if there are three sends in progress to a site, and another higher priority job is activated, the Scheduler will suspend one of the lower priority jobs and start the higher priority job. The lower priority job will be resumed after the higher priority job completes.

Sender can't connect to target site server.

Network connectivity problems can prevent a sender from connecting to a remote server. An unreliable network connection can delay a job, or even cause it to fail.

Insufficient disk space on the target site server.

The sender must transfer the entire package and instruction files to the remote site server. The send will fail if the server does not have adequate disk space.

Sender account or password is invalid at target site.

The sender uses the account and password entered in the Address Properties dialog box. The account and password must be valid on the target site server. There can be multiple addresses for one site, so be sure to check the account name for all addresses in the site. To check an account and password, try to manually connect to the server using the following Windows NT command:

net use \\destserver\ipc$ * /user:[DomainName\]UserName

For instance, for the user BethS in domain Home1 to connect to a server named FarAway:

net use \\FarAway\ipc$ * /user:Home1\BethS

Incomplete account specified in trusted domain environment.

If your organization uses a Windows NT trusted domain model, be sure to specify the domain name when you specify the SMS service account and the site address account. For instance, instead of just specifying the account (for example, SENDACCT), specify the domain and account (for example, BIGDOMAIN\SENDACCT). This ensures that the sender will use the account from the correct domain, even if the same account name exists in other domains.


Despooler Problems

The following are some common reasons why the Despooler might not complete processing a job:

Insufficient disk space on the site or helper server.

The Despooler uses a temporary directory to decompress the package. If the computer that the Despooler is running on does not have enough disk space, then the Despooler cannot complete the job.

Insufficient disk space on the distribution servers.

The Despooler will not be able to complete the job if any of the distribution servers do not have adequate disk space for the decompressed package.

Account or password is invalid on the target distribution servers.

The Despooler distributes the package to the distribution servers using the service account and password specified in the Account dialog box. This account must be valid on all distribution servers in order for the Despooler to complete the job.

Distribution servers do not support package properties.

Distribution will fail if the servers do not support the type of package being distributed. For instance, if your source directory contains Macintosh files, your distribution server must have Windows NT Services for Macintosh installed. Likewise, distribution to a NetWare server will not succeed if the package files use long file names.

Note

If the Despooler successfully distributes the package to some servers (but fails on other servers), it will still create the workstation instruction files for the clients. However, it will only include the successful servers in the instruction files, so clients will only access the package from those servers. If distribution to additional servers succeeds later, those servers will be added to the instruction files.


Troubleshooting Jobs

As described in "Monitoring Jobs" earlier in this chapter, you monitor jobs by checking the job status and status details displayed in the Jobs window, the Jobs Status dialog box, and the Jobs Status Details dialog box. If you observe a problem with a job, you can troubleshoot the job by checking the following:

  • Events in the Events window and in the Windows NT event log.
  • Status of the files that are created, modified, copied, and deleted during the job process.
  • Trace logs for the services that manage the job process.

The following sections describe using events, system flow, files, and trace logs to troubleshoot a job.


Using Events

If an SMS service or component encounters an error while processing a job, it reports an SMS system event to both the Windows NT event log and the SMS event database. You should frequently check the SMS Administrator Events window for errors or warnings. If possible, fix conditions that are generating warnings as well as those generating error conditions. Periodically delete old or duplicate events (if appropriate) to minimize the number of events in the event log. The following dialog box shows the Events window in the SMS Administrator:

Event Attributes

Event attributes are reported in the Event Detail window for each event. The Event Detail window for event number 225 follows:

Events in the Event Detail window have the following attributes:

SMSID

The SMS ID for the computer where the event occurred.

MachineName

The network name of the computer where the event occurred.

Time

The date and time when the event occurred. Time is displayed according to the date and time settings on the computer where the error occurred.

EventID

The identification number that specifies the type of event.

WarningLevel

A number that specifies the severity of the event:

WarningLevel | Severity
0 | Success
1 | Informational
2 | Warning
3 | Error

EventModule

The source of the event. This is the text displayed as the Source for the event in the Windows NT Application Log. For most SMS events, the source is SMS. It is also the registry key used to find the location of the DLL that contains the message strings used to display the event's details within the Windows NT Event Viewer.

EventType

A string that identifies the type of event.

Component

The name of the service or program that logged the event. For the SMS Executive service, Component may display the SMS Executive thread that logged the event.

Note

For Run Command On Workstation jobs, if the job fails to run at a client, the failing component is reported as the Despooler, not as Package Command Manager.

Depending on the type of event and the component that reported the event, the event may also display one of the following attributes:

JobID

If an event affects the processing of a job, this attribute specifies the job ID of the job that was affected.

JobDestination

If an event affects the processing of a job, this attribute is the specific destination site (within the Job Target for the job) that was affected.

PackageID

If an event affects the processing of a job, this attribute is the package ID for the job's package.

RequestID

If an event affects the sending of a job, this attribute specifies the send request that was affected.

Viewing Events

By default, the Events window displays the main attributes for each event. You can also choose how the events and attributes are displayed in the Events window:

  • To choose the attributes that are displayed for each event, from the View menu, choose Partial Details.
  • To filter the events so that only the events that meet the criteria you want are displayed in the Events window, from the View menu, choose Filter.
  • To sort the events, from the View menu, choose Sort.

You can also change the attributes that are displayed in the Events windows by modifying the default query result format for the SMSEvents architecture, which is used to determine the attributes displayed in the Events window.

You can view events individually by opening the Event Detail dialog box for the event whose details you want to view. The Event Detail dialog box displays the main attributes of the event and provides a full description of the event.

Using Events in Queries and Alerts

Events logged as event MIF files are stored as objects with the Event architecture in the database. As with other objects stored in the database (such as computers and user groups), you can create and run queries against the Event architecture to find the events you want to view. You can also run an Ad Hoc query from the Events window by double-clicking the window panel on the Events window.

As with any other query, you can use a query on events to trigger an alert. For example, you could have a query that searches for events with a value of 3 for WarningLevel. You could then specify that query in an alert. When the alert condition evaluates to true, the alert action is triggered. The alert can send a message, run a command, or log an SMS event.

To use queries to find events that are related to a specific job

1. In the SMS Administrator, open the Jobs window and find the job ID for the job you want to query.

2. Open the Queries window and, from the File menu, choose New to create a new query.

3. In the Query Name and Comment boxes, type a query name and comment, respectively.

4. In the Architecture box, select the SMSEvent.

5. Choose Add And.

6. In the Query Expression Properties dialog box, select the line with attribute JobID.

7. Enter the value of the job ID for the job. (Make sure that the Expression Operator is set to is.)

8. Save the query.

9. Run the query.

The events relating to the job are displayed in the Query Results window.

Using this query, you could also create an alert that triggers an action when any events containing the job ID are found in the SMS Event database.

For more information about using events and alerts, see the SMS version 1.2 Administrator's Guide.


Using System Flow

A Run Command On Workstation job runs a command defined for a package at specified clients. You can use a Run Command On Workstation job to install a package or to run a command on individual clients. After the job is created, it is added to the site database.

To troubleshoot a job using system flow, you monitor the files that are created, modified, copied, and deleted during the job process. In order to know which files should be created or modified, you need to reference the system flow descriptions in Chapter 3, "System Flow." The following section describes the basic system flow for a Run Command On Workstation job, and then lists the files and directories to check to make sure that the process has completed successfully, or to find where the process has stalled.

System Flow for a Run Command On Workstations Job

The basic system flow for a Run Command On Workstations job is as follows:

1. The job is created and stored in the SMS database.

2. The Scheduler monitors the database for new jobs. When it is time to process a job, the Scheduler compresses the job package and determines the sites and clients that should receive the job. It then creates the send request files and the despooler instruction files needed to complete the job at the target sites.

3. The sender sends the compressed package and instruction files to all target sites. The sender starts processing the send request file as soon as the Scheduler places the file in its directory. (The sender does not use polling; it receives a Windows NT message whenever a file is placed in its directory.)

If for any reason sending is interrupted, when it resumes it continues from where it left off. If the connection cannot be reestablished, the sender reports this to the Scheduler. The Scheduler postpones the send and tries again later. The Scheduler tries repeatedly to send the job over several days before reporting the job as failed.

4. The Despooler decompresses the package and places it on the specified distribution servers. The Despooler also uses the job's despooler instruction file to create workstation instruction files (WIFs) for each target client.

Normally, the Despooler does not use polling cycles; it receives notification from Windows NT whenever a file is placed in its directory. It then wakes up and begins processing the file. It also wakes up periodically to retry any failed jobs.

While the Despooler is processing the instruction files, it sends job status MIF files back to the site where the job originated. As soon as the Despooler successfully decompresses the package, it sends a site arrival MIF file. After it has successfully distributed the package to a distribution server, the Despooler sends a server MIF file. When the package has been completely distributed, it sends a completion MIF file.

5. The Maintenance Manager replicates the WIFs from the site server to the SMS logon servers. The Maintenance Manager also sends package location MIF files back to the site where the job originated. Like the Scheduler, the Maintenance Manager runs on a polling cycle that is controlled by the Service Response speed that is set in the Site Properties dialog box.

To verify that the Scheduler has processed the job properly

1. Look for the compressed package file and the despooler instruction files, which the Scheduler places in the SITE.SRV\SENDER.BOX\TOSEND directory in the SMS root directory after the job's Start After time elapses.

The file name for the compressed package is packageid.W* where packageid is the eight character package ID for the package used by the job.

The file name for the despooler instruction file is instructionid.I*, where instructionid is the five character unique ID in the job ID followed by the site code for the target site. The despooler instruction files contain instructions for completing the job at each target site. The Scheduler creates a despooler instruction file for each target site.

2. Look for the send request (*.SRQ) files on the site server.

The Scheduler creates a send request file for each target site specified for the job. A send request file contains instructions for sending the compressed package and the despooler instruction file to the target site.

Initially, the *.SRQ file is placed in the appropriate outbox directory (SITE.SRV\SENDER.BOX\ REQUESTS\sender.000 where sender.000 is the specific sender's outbox directory name, such as LAN_DEFA.000, SNA_BATC.000, or RAS_ISDN.000) for the type of sender being used to send the job to the target site. For example, if a package is sent to the target site using the LAN Sender, the SRQ file would be placed in the LAN_DEFA.000 directory of the REQUESTS directory.

To verify that the sender has processed the job properly

1. Look for the sender status (*.SRS) file.

The sender monitors its outbox for a valid send request. When it detects a send request, it renames it to *.SRS to indicate the send is in progress and to report status.

2. At the receiving site, look in the SITE.SRV\DESPOOLR.BOX\RECEIVE directory for the compressed package file and the despooler instruction file.

The sender connects to the target site and transfers the compressed package file and the despooler instruction file from the SITE.SRV\SENDER.BOX \TOSEND directory on the site server to the SITE.SRV\DESPOOLR.BOX \RECEIVE directory on the target site server. The Despooler renames the compressed package to *.PCK. When the instruction file is being transferred, it is named *.TMP; once the package and instruction file are received and verified, the instruction file is renamed to *.INS.

To verify that the Despooler has processed the job properly

1. Monitor the SITE.SRV\ DESPOOLR.BOX\STORE directory on the site server for the target site.

The Despooler monitors the SITE.SRV\DESPOOLR.BOX\RECEIVE directory for instruction files and then processes the files. The Despooler moves the compressed package to the SITE.SRV\ DESPOOLR.BOX\STORE directory. Workstation packages are saved as packageID.WKS (shared packages are saved as packageID.SRV).

2. Check for a temporary decompressed copy of the package.

The Despooler recreates the original package by decompressing the .WKS (or .SRV) file at the specified servers. The Despooler decompresses the package directory into a temporary directory located on the local drive's root directory with the most space.

3. Confirm that the Despooler has distributed the package to the distribution servers in the site.

On computers running Windows NT and LAN Manager, the Despooler creates an SMS_PKGx share on each distribution server, where x is the drive where the package is placed. Then the Despooler creates a subdirectory and places the package in that subdirectory.

On NetWare servers, the package is placed beneath the LOGON.SRV \PCMPKG.SRC directory on the volume containing the SMS logon server components. The name of this subdirectory is the package ID name.

For more information about how the Despooler places packages on distribution servers, see Chapter 3, "System Flow."

4. Check WIFs in the master domain box on the site server.

For a Run Command On Workstation job, the Despooler uses the job's despooler instruction file to create a WIF for each target client in the site's domains. WIFs contain package installation instructions for individual clients. For each domain in the site, WIFs are placed in a domain master box. The domain master box directory is SITE.SRV\ MAINCFG.BOX\PCMDOM.BOX\domain_name.000. The WIFs are named with the client SMS ID, and an extension of INS (SMS_ID.INS).

To verify that the Maintenance Manager has processed the job properly
  1. Confirm that the Maintenance Manager has replicated the WIFs from the site server to the SMS logon servers.

The Maintenance Manager replicates the WIFs from the SITE.SRV \MAINCFG.BOX\PCMDOM.BOX\domain_name.000 directories on the site server to the LOGON.SRV\PCMINS.BOX directory on all the SMS logon servers in the target SMS domains.

When all of these processes have completed, the package should be available to the appropriate SMS clients.


Using Trace Logs

SMS employs a number of services to accomplish its tasks. Most SMS services (such as the Hierarchy Manager) consist of a single service component managing one basic task. However, one service (the SMS Executive) consists of a number of service components managing a number of different tasks. Many of the services (including the two already mentioned) are limited to a single copy per site; however, some services and components can support multiple copies running in a site (for instance, you may have multiple senders within a site, and services like the Client Configuration Manager run on every SMS logon server running Windows NT Server).

When tuning or troubleshooting an SMS system, it is extremely important to understand the services and how they are performing. A key indicator is the service trace logs. These logs record the specific actions each service takes, and any errors that are encountered. The log files are ASCII text files that can be viewed with a text editor. Viewing the log files can help you monitor the system and diagnose problems.

Services or components installed on multiple servers (such as senders, Client Configuration Manager, Inventory Agent, and Package Command Manager) read the trace log configuration from the registry of the site server. For example, the Inventory Agent for Windows NT installed on an SMS logon server uses the tracing setting specified for the Inventory Agent on the site server.

The size of the log files is determined by the Trace Log Maximum Size setting, and the amount of data logged. The Trace Log Maximum Size setting determines the maximum size of the trace file. When enough data has been logged so that the file reaches the maximum size, the service renames the current file and starts a new log file. The backup log file has the same name as the active log file, except that the extension for the backup log file has a trailing underscore. For example, the primary log file for the Despooler is called DESPOOL.LOG; the backup log file is called DESPOOL.LO_. If a backup log file already exists, the component overwrites that backup log file when it backs up the log file again.

Because the service keeps a backup log file, the actual amount of data logged can be up to twice the size of the maximum value you set. For example, if you set the Trace Log Maximum Size to 1 MB, you can have up to 2 MB of logged data—1 MB for the active log file and 1 MB for the backup log file. Therefore, when you plan the amount of disk space taken by a component for trace logging, you should plan for twice the size of the Trace Log Maximum Size setting.

Default Services, Registry Keys, and Log File Names

The default log files for SMS services and components are defined in the following table.

Service/component | Registry key | Log file name
Alerter | SMS_ALERTER | ALERTER.LOG
Applications Manager | SMS_APPLICATIONS_MANAGER | APPMAN.LOG
Bootstrap | SMS_BOOTSTRAP | BOOT.LOG
Client Configuration Manager | SMS_CLIENT_CONFIG_MANAGER | CLICFG.LOG
Despooler | SMS_DESPOOLER | DESPOOL.LOG
Hierarchy Manager | SMS_HIERARCHY_MANAGER | HMAN.LOG
Inventory Agent | SMS_INVENTORY_AGENT_NT | INVAGENT.LOG
Inventory Data Loader | SMS_INVENTORY_DATA_LOADER | DATALODR.LOG
Inventory Processor | SMS_INVENTORY_PROCESSOR | INVPROC.LOG
LAN Sender | SMS_LAN_SENDER | LANSEND.LOG
Maintenance Manager | SMS_MAINTENANCE_MANAGER | MAINTMAN.LOG
Package Command Manager | SMS_PACKAGE_COMMAND_MANAGER_NT | PACMAN.LOG
RAS Sender (Asynchronous) | SMS_ASYNC_RAS_SENDER | RASASYNC.LOG
RAS Sender (ISDN) | SMS_ISDN_RAS_SENDER | RASISDN.LOG
RAS Sender (X.25) | SMS_X25_RAS_SENDER | RASX25.LOG
Scheduler | SMS_SCHEDULER | SCHED.LOG
Site Configuration Manager | SMS_SITE_CONFIG_MANAGER | SCMAN.LOG
Site Reporter | SMS_SITE_REPORTER | SITEREPT.LOG
SMS Executive | SMS_EXECUTIVE | SMSEXEC.LOG
SMS Administrator | SMS_USER_INTERFACE | UI.LOG
SNA Sender (BATCH) | SMS_BATCH_SNA_SENDER | SNABATCH.LOG
SNA Sender (INTER) | SMS_INTER_SNA_SENDER | SNAINTER.LOG
SNA Receiver | SMS_SNA_RECEIVER | SNARECV.LOG
SNMP Trap Receiver | SMS_TRAP_FILTER | TRAPFLTR.LOG

Controlling Service Tracing

By default, tracing is turned on for both primary and secondary sites. All services are enabled for tracing, and the default trace log file size is set to a maximum of 128K. There are two ways to modify tracing properties:

  • Use the SMS Service Manager to turn tracing on or off for each service or for each component in the SMS Executive.

Note

Using the SMS Service Manager to change the state of SMS Executive changes the state of all components within SMS Executive. For example, stopping SMS Executive stops all components within SMS Executive. You should not stop or start individual components in SMS Executive; stop or start SMS Executive itself.

  • Use the Windows NT Registry Editor to edit the values for the service keys beneath the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key. To force a service to use its TRACING key entry, you must stop and restart the service. You can use the SMS Service Manager to stop and restart the services.

The SMS Service Manager is documented in the SMS version 1.2 Administrator's Guide. Controlling tracing using the registry is described in the following section.

Controlling Tracing for all Services and Components in a Site

The TRACING key has two values (Enabled and SQL Enabled) and subkeys for all SMS services and components. (The subkeys are used to set tracing for individual services and components, and are discussed in the following section.)

The Enabled value in the TRACING key lets you turn on tracing for the site.

The SQL Enabled value enables SMS components and services that access SQL Server to log SQL Server actions to the trace logs of those components and services.

To control tracing for all services and components in the site

1. On the site server, start the Windows NT Registry Editor (regedt32).

2. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key.

3. To turn on tracing for the site, set the Enabled value in the TRACING key to 1. To turn tracing off, set the key to 0. To turn on tracing for SQL Server, set the SQLEnabled value in the TRACING key to 1. To turn tracing off, set the key to 0.

Controlling Tracing for Individual Services and Components in a Site

If you want to control the tracing for each service and component individually, you can do this by setting the subkeys under the TRACING key in the registry.

To control tracing for individual services and components

1. On the site server, start the Windows NT Registry Editor (regedt32).

2. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key.

3. Select the service or component for which you want to set a different tracing option (for example, SMS_ALERTER).

4. Set the Enabled value for the service or component's subkey below the TRACING key.

Set the value to 1 to enable tracing and 0 to disable tracing. For services, the subkey name corresponds to the service name. For components within the SMS Executive service, the subkey name corresponds to the component name. (The SMS_USER_INTERFACE key is for the SMS Administrator.)

Setting the Trace Log Path and File Name

All of the trace files for the SMS services and components are assigned a default path and file name. However, you can specify different trace log paths and file names for each service and component. You can also specify that all services and components use the same trace log file and file name. For more information about the default service and component file names, see "Default Services, Registry Keys, and Log File Names" earlier in this chapter.

The path is a relative path to the drive where the component or service is running. When a service reads the registry to get the path and file name of its trace log file, it adds the drive letter for the drive where the service is running. For example, if the trace log path for the Maintenance Manager is SMS\LOGS \MAINTMAN.LOG and Maintenance Manager runs from drive D, the trace log path is D:\SMS\LOGS\MAINTMAN.LOG.

If the directories in the path do not exist, the component creates the directories. If the file name is specified without a path, the service or component uses the first directory in its path. (This is not recommended since it makes the trace log files difficult to find.)

When specifying a trace log file name, you can use a UNC path; however, this is not recommended, especially for components and services that are installed on multiple computers in a site such as senders, the Inventory Agent, and the Package Command Manager. If you specify a UNC name, all of the copies of the services and components in a site write to the same trace log file. In addition, using a UNC path can cause excessive network traffic.

To set the path and name of the trace log file

1. On the site server, start the Windows NT Registry Editor (regedt32).

2. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key.

3. Select the service or component for which you want to set a different tracing option.

4. In the TraceFilename key, set the value for the path and file name.

Setting the Trace Log File Size

You can set the maximum size of the trace log file for individual services or components. To set the maximum file size for a component's log file, you add a MaxFileSize value in the component's tracing key. The value must have a data type of REG_DWORD. The data for the value specifies the size of the log file in bytes. If no MaxFileSize value exists, the log file size is the default (128K). For troubleshooting purposes it is often useful to increase the log file size sufficiently such that the logs can hold a full 24 hours worth of data.

To set the trace log file size

1. On the site server, start the Windows NT Registry Editor (regedt32).

2. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key.

3. Select the service or component for which you want to set a different tracing option.

4. From the Edit menu, choose Add Value.

The Add Value dialog box appears.

5. In the Value Name box, type MaxFileSize.

6. In the Data Type box, select REG_DWORD.

7. In the DWORD Editor dialog box, in the radix field, choose Decimal, and then enter the file size for the log file.

The service will keep a backup copy of the log file, so the log files will actually require twice the amount of disk space specified.

Controlling Tracing for a Component Running as an Executable

You can set up tracing for a component of SMS Executive running as an executable instead of as a service (you may want to do this for diagnosing problems in SMS Executive). The executable will display its tracing output directly to the computer display.

To control tracing for a component running as an executable

1. On the site server, start the Windows NT Registry Editor (regedt32).

2. Open the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS \TRACING key.

3. Select the component that is running as an executable. Set the Enabled value in the TRACING key to 2. To turn tracing off, set the key to 0.

Using Trace Logs to Troubleshoot Jobs

The log file for a component has the file name and location specified by the component's key beneath the TRACING key. You can use an ASCII text editor or word processor to view the trace log for a component. You can also use tracing tools provided in this resource kit. For more information about tracing tools, see SMSTOOLS.HLP.

Each line (a line is a string, terminated with an end of line character) in the log file is an action reported by the component. Each line begins with a description of the action. The description ends with two dollar signs ($$). After the description, the component name is enclosed within angle brackets. The component name is followed by the date and time within angle brackets. The date and time is followed by the thread ID within angle brackets.

An example of the data in a trace log for the Scheduler follows:

        Sending completed (0 bytes/sec).~   $$<SMS_SCHEDULER><Mon Jul 18 22:28:57 1996~><thread=C1>
MEMORY USAGE:  45103 bytes in 1595 allocations.~   $$<SMS_SCHEDULER><Mon Jul 18 22:28:58 1996~><thread=C1>
========  Sleeping for 300 seconds  ========~
$$<SMS_SCHEDULER><Mon Jul 18 22:28:59 1996~><thread=C1>
========  Processing cycle ( 07/18/96 22:33:59 )  ========~
$$<SMS_SCHEDULER><Mon Jul 18 22:33:59 1996~><thread=C1>
UPDATING JOB T100000B~   $$<SMS_SCHEDULER><Mon Jul 18 22:34:01 1996~><thread=C1>
<JOB T100000B>~   $$<SMS_SCHEDULER><Mon Jul 18 22:34:01 1996~><thread=C1>
    Updating status of "Run Command at Workstation" job.~
$$<SMS_SCHEDULER><Mon Jul 18 22:34:01 1996~><thread=C1>
Updating status for request T10000B for destination T10.~
$$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
Updating status for request T10000B for destination T10.~
$$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
    <JOB STATUS - ACTIVE>    $$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
 <SEND STATUS - COMPLETE>    $$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
 <WORK STATUS - ACTIVE>~   $$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
UPDATING JOB T1000014~   $$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
<JOB T1000014>~   $$<SMS_SCHEDULER><Mon Jul 18 22:34:08 1996~><thread=C1>
Mapping Job Type and Status in the Log Files

In some of the log files, the Job Type and Status attributes are written as numbers. The following table lists the numbers that correspond to the displayed job type or status in the Job Status dialog box.

Numeric value | Job type | Status
1 | Arrival | Pending
2 | Workstation | Active
3 | Server | Canceled
4 | Completed | Complete
5 | Reserved | Failed
6 | Reserved | Retrying

Reading the Scheduler Log

The Scheduler reports its actions to the SCHED.LOG file. Entries in the SCHED.LOG are reported by job ID.

The following sample log file trace shows that the Scheduler is busy creating (compressing) the package file:

Creating package file '\\SMS SITE\SMS_SHRd\site.srv\Sender.box\tosend\DPW00002.W00'.~
$$<SMS_SCHEDULER><Sun Oct 20 15:48:32 1995~><thread=7D>

When the Scheduler submits a job to a sender, it assigns a send request number for the send request. In order to determine the send request number, search for the job ID in the SCHED.LOG file (the job ID is displayed in the Jobs window). Then look for the text Send Request associated with the job ID.

For example, the following trace shows that job DPW000AE has the send request number 30008DPW:

~====  Send requests found in outbox \\SMS SITE\SMS_SHRd\site.srv\schedule.box.~~   $$<SMS_SCHEDULER><Fri Oct 20 19:32:33 1995~><thread=92>
Send Request 30008DPW~    Job:        DPW000AE  DestSite:  DPW~    State:      Pending   Status:               Action:    None~    Total size: 00397693  Remaining: 00397693   Heartbeat: 15:49~    Start:      12:00     Finish:    12:00      Retry:          ~
$$<SMS_SCHEDULER><Fri Oct 20 19:32:33 1995~><thread=92>
Send Request 30009DPW~    Job:        DPW000AF  DestSite:  DPW~    State:      Pending   Status:               Action:    None~    Total size: 00397694  Remaining: 00397694   Heartbeat: 19:32~    Start:      12:00     Finish:    12:00      Retry:          ~
$$<SMS_SCHEDULER><Fri Oct 20 19:32:33 1995~><thread=92>

Reading the Sender Log

After you have determined that the Scheduler has submitted the send request to a sender, look in the appropriate sender log for the send request number. For instance, if the send request was submitted to a LAN Sender, look in the LANSEND.LOG file and search for the send request number.

In the following example, the send request number is 30008DPW.

Found send request.  ID: 30008DPW, Dest Site: DPW~
$$<SMS_LAN_SENDER><Fri Oct 20 19:34:46 1995~><thread=A3>
~We have 0 active connections   $$<SMS_LAN_SENDER><Fri Oct 20 19:34:46 1995~><thread=A3>
Checking for site-specific sending capacity.  Used 0 out of 1.~
$$<SMS_LAN_SENDER><Fri Oct 20 19:34:46 1995~><thread=A3>
~We have 0 active connections   $$<SMS_LAN_SENDER><Fri Oct 20 19:35:47 1995~><thread=A3>
~Created sending thread (Thread ID = 110)   $$<SMS_LAN_SENDER><Fri Oct 20 19:35:47 1995~><thread=A3>

This example shows that the sender has found the send request, and created a sending thread (thread ID = 110) to send the job. Before it created the thread, it verified that it had threads available, and that there were no connections to the destination site.

To continue monitoring the send status, you must use the thread number at the end of each log entry. If multiple threads are active, the messages from the different threads may be intermingled in the log file.

The following example shows a trace log with two active threads. The file name is the package ID (not the job ID nor the send request number). The file type begins with a W (W01 in the following example) to indicate a Run Command On Workstation job. An S is used to indicate a Share Package On Server job.

~Wrote 133871 bytes to d:\dpw692\SITE.SRV\despoolr.box\receive\30008DPW.PCK
$$<SMS_LAN_SENDER><Fri Oct 20 19:35:50 1995~><thread=110>
~We have 1 active connections   $$<SMS_LAN_SENDER><Fri Oct 20 19:36:20 1995~><thread=A3>
~Sending completed [D:\dpw692\site.srv\Sender.box\tosend\DPW00002.W01]
$$<SMS_LAN_SENDER><Fri Oct 20 19:36:20 1995~><thread=110>
Checking for sending capacity.  Used 1 out of 1.~
$$<SMS_LAN_SENDER><Fri Oct 20 19:36:20 1995~><thread=A3>

Reading the Despooler Log

After you have determined that the sender has completed sending the package and the job instructions to a target site, you can look in the despooler log (DESPOOL.LOG) to see if the Despooler has started processing the instruction file.

The following trace shows the Despooler processing the instruction file for job DPW000AE. The instruction file has the send request number as the instruction file name (30008DPW.INS). The Despooler also reports the job ID and package ID.

~Found ready instruction 30008dpw.ins   $$<SMS_DESPOOLER><Fri Oct 20 20:14:42 1995~><thread=A4>
~Executing instruction of type Microsoft|SMS|WorkstationInstall
$$<SMS_DESPOOLER><Fri Oct 20 20:14:42 1995~><thread=A4>
~Successfully read the instruction file   $$<SMS_DESPOOLER><Fri Oct 20 20:14:42 1995~><thread=A4>
~Start processing Workstation job, Job ID = DPW000AE, Package ID = DPW00002   $$<SMS_DESPOOLER><Fri Oct 20 20:14:42 1995~><thread=A4>

The following trace shows the Despooler determining where to decompress the package, and doing the decompression. The Despooler completely recreates the directory structure of the original source tree.

~The package file doesn't require a NTFS drive to decompress to.
$$<SMS_DESPOOLER><Fri Oct 20 20:14:43 1995~><thread=A4>
~D drive has the most free space, we'll use it for temp storage.
$$<SMS_DESPOOLER><Fri Oct 20 20:14:43 1995~><thread=A4>
~Decompressing package W_DPW00002 to D:\_S M0000.TMP
$$<SMS_DESPOOLER><Fri Oct 20 20:14:43 1995~><thread=A4>

After the package has been decompressed, the Despooler distributes the package to the specified distribution servers. The following example shows the Despooler creating the package share on a distribution server, and then copying the package files to the server.

~D drive on server \\SMS SITE is the suitable drive with most free space.   $$<SMS_DESPOOLER><Fri Oct 20 20:14:58 1995~><thread=A4>
~Creating share SMS_PKGD on server \\SMS SITE with path D:\SMS_PKGD
$$<SMS_DESPOOLER><Fri Oct 20 20:14:59 1995~><thread=A4>
~Setting permissions on \\SMS SITE\SMS_PKGD\DPW00002 for package W_DPW00002   $$<SMS_DESPOOLER><Fri Oct 20 20:14:59 1995~><thread=A4>
~Finished setting permission on \\SMS SITE\SMS_PKGD\DPW00002
$$<SMS_DESPOOLER><Fri Oct 20 20:15:00 1995~><thread=A4>
~Copying package from D:\_S M0000.TMP to \\SMS SITE\SMS_PKGD\DPW00002   $$<SMS_DESPOOLER><Fri Oct 20 20:15:00 1995~><thread=A4>
~Copying D:\_S M0000.TMP\itg.dir to d:\SMS_PKGd\DPW00002\itg.dir, OK
$$<SMS_DESPOOLER><Fri Oct 20 20:15:03 1995~><thread=A4>
~Copying D:\_S M0000.TMP\itg2.dir to d:\SMS_PKGd\DPW00002\itg2.dir, OK
$$<SMS_DESPOOLER><Fri Oct 20 20:15:05 1995~><thread=A4>
~Package W_DPW00002 is installed on server \\SMS SITE, register it in the registry   $$<SMS_DESPOOLER><Fri Oct 20 20:15:06 1995~><thread=A4>

If the Despooler has to distribute the package to multiple servers, it copies the files from the temporary directory to the other servers. Then the Despooler creates the WIFs for the clients (the Package Command Manager on the clients reads these instruction files). In the trace logs, the WIFs are called WINST files.

~Ready to create WINST instructions.   $$<SMS_DESPOOLER><Fri Oct 20 20:15:06 1995~><thread=A4>
~Found WINST package server SMS SITE   $$<SMS_DESPOOLER><Fri Oct 20 20:15:06 1995~><thread=A4>
~Setting the WINST instruction file, the package path is \\SMS SITE\SMS_PKGD\DPW00002\, the server type is 2, the zone is
$$<SMS_DESPOOLER><Fri Oct 20 20:15:06 1995~><thread=A4>
~Setting winst instructions for domain DWDOM   $$<SMS_DESPOOLER><Fri Oct 20 20:15:06 1995~><thread=A4>
~Setting WINST data for machine BVT00001 in domain DWDOM
$$<SMS_DESPOOLER><Fri Oct 20 20:15:07 1995~><thread=A4>
~Setting WINST data for machine BVT00002 in domain DWDOM
$$<SMS_DESPOOLER><Fri Oct 20 20:15:07 1995~><thread=A4>
~Setting WINST data for machine BVT00003 in domain DWDOM
$$<SMS_DESPOOLER><Fri Oct 20 20:15:08 1995~><thread=A4>
~Setting WINST data for machine DPW05000 in domain DWDOM
$$<SMS_DESPOOLER><Fri Oct 20 20:15:08 1995~><thread=A4>

After the Despooler distributes the package files to all distribution servers, it deletes the temporary directory it created earlier.

~ Deleting D:\_S M0000.TMP...   $$<SMS_DESPOOLER><Fri Oct 20 20:15:08 1995~><thread=A4>
~Deleted D:\_S M0000.TMP   $$<SMS_DESPOOLER><Fri Oct 20 20:15:08 1995~><thread=A4>
~Despooler successfully executed one instruction.
$$<SMS_DESPOOLER><Fri Oct 20 20:15:08 1995~><thread=A4>

Reading the Maintenance Manager Log

The Maintenance Manager copies the WIFs to all SMS logon servers. After this is done, the Package Command Manager (running on the clients) can offer the new job to clients.

The following trace shows the Maintenance Manager copying the WIFs to the four SMS logon servers in the DWDOM domain.

~Working on logon server SMS SITE   $$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:35 1995~><thread=D6>
~Replicating WINST instructions   $$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:35 1995~><thread=D6>
~Copying d:\dpw692\site.srv\maincfg.box\pcmdom.box\DWDOM.000\BVT00001.INS to d:\dpw692\logon.srv\pcmins.box\BVT00001.INS, OK
$$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:35 1995~><thread=D6>
~Copying d:\dpw692\site.srv\maincfg.box\pcmdom.box\DWDOM.000\BVT00002.INS to d:\dpw692\logon.srv\pcmins.box\BVT00002.INS, OK
$$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:36 1995~><thread=D6>
~Copying d:\dpw692\site.srv\maincfg.box\pcmdom.box\DWDOM.000\BVT00003.INS to d:\dpw692\logon.srv\pcmins.box\BVT00003.INS, OK
$$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:36 1995~><thread=D6>
~Copying d:\dpw692\site.srv\maincfg.box\pcmdom.box\DWDOM.000\DPW05000.INS to d:\dpw692\logon.srv\pcmins.box\DPW05000.INS, OK
$$<SMS_MAINTENANCE_MANAGER><Fri Oct 20 20:51:36 1995~><thread=D6>


Glossary


A

ad hoc query

A query created for immediate execution. Ad Hoc queries are not stored in the SMS system database, do not affect any queries in the database, and are not displayed in the Queries window. You can create an Ad Hoc query from scratch or by modifying an existing query.

address

Specific information for connecting to a target site so that instructions and data can be sent to that site.

alert

A set of actions that depend on the results of a specified query. An alert defines how the SMS system should detect a specific condition, using a query, and what actions it should take when that condition is detected. For example, an alert can log an SMS event, run a command from the computer where the Alerter is installed, and send a message to a computer or user on the local network. See also Alerter.

Alerter

An SMS component (within the SMS Executive service) that processes alerts by evaluating alert conditions and triggering alert actions when the conditions are true. The Alerter also monitors the database for new alerts and any changes to existing alerts. See also alert.

APPCTL

A program that is part of the Program Group Control feature on SMS clients. This SMS program creates the assigned program groups in the client's Program Manager.

Applications Manager

An SMS component (within the SMS Executive service) that communicates package and program group configuration information from the site database to the other components at that site and to the sites beneath it.

Applications Manager database

A set of configuration files used by the Program Group Control feature at Windows-based SMS clients. The Applications Manager is installed on all SMS logon servers. At Windows-based clients, the APPCTL program connects to an SMS logon server and collects all program groups assigned to the user logged on at that client. Then it builds the program groups in the Program Manager.

APPSTART

An SMS program that is part of the Program Group Control feature on SMS clients. APPSTART lets users start and run SMS network applications that are assigned to them. When a user launches an assigned SMS network application, APPSTART automatically makes the connection to the appropriate server and, along with APPCTL, sets up the proper execution environment for the application.

architecture

A structure for recording inventory for a specific type of object. An architecture defines the structure for a set of objects. Each object is composed of groups that contain attributes. See also attribute and object.

attribute

A property of a group. Each attribute is assigned a value. The set of attribute values for a group comprises the inventory for the component.

audited software

A set of software items that you define. Each software item is defined by the set of files (and their attributes) that you want to use to identify that item. At clients, the user can run the Software Audit program, which scans for these items and reports the items that were found.


B

bottleneck

A single component that degrades system performance. Bottleneck is also used to describe the condition in which the limitations in one component prevent the whole system from operating faster.

A bottleneck results in low rates of use on components, sustained queues for one or more services, and slow response time.


C

central site

The primary site that stores system-wide information and manages all sites, with any number of subsites beneath it. The central site is a primary site where all other sites in the SMS system report their inventory and events. When you build a site hierarchy, child sites report their inventory to their parent sites, the parent sites report their inventory and their child sites' inventory to their parent sites, and so on up to the central site. At the central site, you can manage software and view the inventory for any computer in any site in the SMS system. The central site is a primary site that has no sites above it.

child site

A site that has a parent site. A child site can be a primary site that has been attached to another primary site. A child site can also be a secondary site (a secondary site is always the child site of the primary site that created the secondary site).

clause (query)

In a query, the combination of an expression (or subclause) and its adjacent logical operator. See also subclause.

client

A computer connected to a network and running network client software.

Client Monitor

A program that monitors changes on the SMS logon servers that must be copied to clients, and copies inventory files from the client to the SMS logon server.

command (package command)

A command line in Run Command On Workstation jobs that runs a program on target clients. A command can be used to install a package (such as an application like Microsoft Excel) or to just run a program (such as a virus scan utility).

community

An administrative relationship between SNMP entities.

conventional memory

The lower 640K (or less) of main memory. The remaining portion of main memory, up to 1 MB, is called upper memory. Beyond 1 MB, an MS-DOS – based computer's memory is either expanded memory or extended memory. The memory map does not map beyond upper memory.

CRC-CCITT

A standard algorithm that calculates the sum of all values stored at a specific set of bytes and compares the sum to a specified value. Unlike CHECKSUM, CRC-CCITT takes into account the sequence of the summed bytes, making it a more reliable tool for identifying files.

current site

The primary site whose database you have logged in to with the SMS Administrator.
In the Sites window of the SMS Administrator, the current site is represented as a primary site with a globe.


D

database server

A computer running Microsoft SQL Server on which the SMS site database for a site is installed.

default servers machine group

A special machine group used for processing jobs at target sites. The default servers machine group specifies the servers where package source directories are installed:

  • If Default Servers is selected as the target for distribution servers.
  • If a target site does not contain any of the servers specified by Put On New Distribution Servers.

At each site, the SMS system creates the default servers machine group. By default, the default servers machine group contains only the site server.

Delta-MIF

A binary file with information stored in the Management Information Format standard and used by the SMS services to add information to the site database.

Despooler

An SMS component (within the SMS Executive) that watches for despooler instruction files and compressed packages created by the Scheduler (the instructions and packages can come from the local site or from another site). The Despooler reads the instruction file and uses the instructions to decompress and handle the package files. For example, it decompresses inventory files so they can be processed by the Inventory Data Loader, which then updates the database.

distribution

See package distribution.

distribution server

A server on which the source directory of a sent package is stored and made available at a site. They are called distribution servers because they have a distributed copy of the package's source directory.

For Run Command On Workstation jobs, a distribution server is a computer on which the source directory of a sent package is stored and made available to the target clients.

For Share Package On Server jobs, a distribution server is a computer on which the source directory of a sent package is stored and shared. The shared package on the distribution server can be used for running the SMS network applications contained in the package. Distribution servers are the servers from which the users at clients run SMS network applications.

domain

For Windows NT and LAN Manager networks, a domain is an administrative unit based on a database of security and user account information shared by a set of servers. For servers running LAN Manager and Windows NT Server, a domain supplies centralized security and user account information for a group of servers. When a user at a client running LAN Manager or Windows NT logs on to a domain, that client participates in that domain while that user is logged on.

For NetWare networks, a domain is based on a group of NetWare servers on a LAN. The servers in a NetWare domain are specified when the domain is added to a site.


E

expression (query)

An instruction to search for objects that have a specified relationship to a specified value for a specified attribute.

An expression compares a specified value against a specific attribute, using an operator (such as is equal to or is like). An expression is made up of an attribute, an operator, and a value.


G

group (query)

A set of expressions that are explicitly held together with parentheses. By making a set of expressions a group, you ensure that the group's expressions are treated as a single entity. Groups have a higher operator precedence than the logical operators (AND and OR). You can use groups to help make complex queries easier to read.


H

helper servers

SMS Logon servers running SMS components that have been moved from the site server (Scheduler, Despooler, and Inventory Data Loader) or simply installed to those servers (the sender components).

Hierarchy Manager

An SMS service that monitors the site database for changes to the configuration of that site or its direct secondary sites. If the Hierarchy Manager detects a change in a site's proposed configuration, it creates a site control file (which contains all proposed configurations for a site) and sends it to the site. The Hierarchy Manager exists only in primary sites.

hit count (query result)

The number of objects that the SMS system has found in the site database, according to the criteria specified by a query.


I

identification group

A collection of attributes that uniquely identify a computer.

installation

Creation of a Run Command On Workstation job. A Run Command On Workstation job enables you to run a package command line at target clients. The command line can start an executable file, batch file, or Microsoft Test script to install the package or simply to run a command.

installation script

A file of script commands that a shell program (for example, Microsoft Test) uses to automate a setup program.

instance (inventory/query)

A single occurrence of a group in the inventory for an object.

Some groups (such as Disk Drives and Software Packages) can have multiple instances on a single client. For example, a client can have multiple instances of the group Software Packages — one for each package installed (such as a Microsoft Excel version 4.0 package, a Microsoft Word version 2.0 package, and so on).

Other groups logically or physically can have only a single instance (such as the Identification and Mouse).

inventory

The information that SMS collects for each computer on the network. The inventory includes hardware (CPU, BIOS, drive information, and so on), software (specified packages), and collected files.

Inventory Agent

A component that scans a computer for hardware and software inventory and reports the inventory to the SMS system.

On clients, the Inventory Agent is a program that is run from SMS logon servers. When a user runs the SMSLS batch file, the Inventory Agent is executed from within the SMSLS batch file.

On computers running Windows NT Server and LAN Manager, the Inventory Agent is a service (Inventory Agent for Windows NT and Inventory Agent for OS/2) that reports inventory every 24 hours. For NetWare servers, the Maintenance Manager performs inventory on NetWare logon servers.

Inventory Data Loader

An SMS component (within the SMS Executive service) that monitors the SMS system for Delta-MIFs (which store information about computer inventory, job status, and events) used to update the database.

inventory frequency

The interval at which the Inventory Agent scans a computer for inventory. Each site has settings for inventory frequency. A site's inventory frequency settings apply to all clients in the site.

The inventory frequency is the time between the last scan and the current time when the Inventory Agent is invoked, either from a logon script or explicitly from the command line. The Inventory Agent scans for two types of inventory: hardware and software. You can set the frequency independently for both hardware and software scanning.

Inventory Processor

An SMS component (within the SMS Executive service) that collects all the RAW files created by the Inventory Agent and creates a history file for each computer (an image of the last RAW file). When new RAW files are ready, it compares them with the history files and writes changes to inventory files called Delta-MIFs. The Inventory Processor also converts MIF files in the ISVMIF directory into Delta-MIFs.

inventory rule

The set of files used to identify the package. To detect each file, specify its attributes (such as file date, file size, CRC, and so on). The SMS inventory system uses this criteria to identify a software package on individual computers and to include it in the computer inventory.


J

job

An object that stores instructions for actions that the system performs. For example, you can define a Run Command On Workstation job to install a package on clients or SMS can create a job to maintain part of the system.


L

LAN Sender

See sender.

logical operator

Connector between two expressions, two subclauses, or a combination of an expression and a subclause. A logical operator defines the relationship between two adjacent expressions or subclauses.

There are two logical operators: AND and OR. AND takes precedence over OR.

logon server

See SMS logon server.


M

machine group

An alias for a group of computers. A machine group is a list of the computers. You use a machine group as a shortcut for referring to multiple computers — instead of having to refer to each computer in a group individually, you can include them in a machine group and use the machine group name.

Machine groups can be used to specify the job targets for Run Command On Workstation jobs and used to specify distribution servers for Share Package On Server jobs.

Maintenance Manager

An SMS component (within the SMS Executive service) that installs and maintains the SMS components on the SMS logon servers at a site. It replicates client components and configuration information to SMS logon servers within the site and collects inventory and status information.

Management Information Format

A standard for accessing desktop computer components (hardware and software) across multiple platforms. This interface was designed by the Desktop Management Task Force.

mandatory package

A package command that must be run by the user from the Package Command Manager at an SMS client before the user can continue working on their computer.

MIF file

A management information format (MIF) file is an ASCII text file that contains information about a computer component. A MIF file is a description of the component that is available to other applications through a standard management interface.

MIF files can be ASCII text or binary (formerly called a delta MIF file). Binary MIF files are used by SMS services to add information to a site database.

ISVMIF files are generated by independent software vendors (ISVs) to report objects such as computers that have custom architectures. IDMIF files contain inventory information. NOIDMIF files report inventory information that contains groups with no ID or architecture.


N

named pipes

An interprocess communication (IPC) method used to transfer data between separate processes, usually on separate computers. You can set permissions on named pipes.

network application

See SMS network application.

Network Monitor

An SMS utility used to capture, edit, transmit, and display frames from the LAN.


O

object

An item (whose structure is defined by its architecture) stored in the site database. For example, a Macintosh computer is an object with the Personal Computer architecture.

optional package

A package command that can be run by the user at any time (or not at all) from the Package Command Manager on an SMS client.

outboxes

Directories where SMS services can put send request files, which contain instructions for transferring data and instructions to other sites. There is a separate outbox for each type of sender.


P

package

An SMS object that contains diverse information about software so that the software can be identified and installed.

A package is an object that defines software to the SMS system. When you create a package, you define the files that comprise the software, and the package's configuration and identification information. After you create a package, you can use the SMS system to install the package on clients, share the package so that it can be run from network servers, or maintain inventory on the package.

package command

A command line (within a package) that runs a program or runs an installation script that installs an application. A package can have multiple package commands defined. When you use a package in a Run Command On Workstation job, you choose the specific package command that you want to run at the job's target computers.

Package Command Manager

An SMS program that runs package commands on SMS clients. The Package Command Manager lets users see the packages that are available and control the installation of optional packages. Mandatory packages are automatically installed by the Package Command Manager.

There is a different version of the Package Command Manager for each supported operating system. On SMS logon servers running Windows NT Server, the Package Command Manager is installed as a service.

package definition file (PDF)

An ASCII text file that contains pre-defined Workstations, Sharing, and Inventory property settings for a package. When you create a new package, you can use the Import command from the Package Properties dialog box to define the properties for the package, using a PDF. By importing a PDF, SMS uses the PDF's property definitions to enter the package properties for you. SMS includes PDFs for some of the more popular applications (such as Microsoft Excel).

package distribution

An action that is performed with a package. Distribution means placing a package on servers and making the package available from a shared directory.

For Run Command On Workstation jobs, distribution installs the package's Workstation source directory on the specified distribution servers at the target sites, shares the directories on the network, and makes them available to the Package Command Manager.

For Share Package On Server jobs, distribution installs the package's Sharing source directory on the specified servers, shares the directories on the network, and makes them available to users with the specified permissions. The package can be used as just a shared directory or as an SMS network application.

package source directory

A shared directory that contains a package's source files. For each package, one source directory can be specified for Workstations properties and another source directory for Sharing properties.

parent site

A primary site to which another site has been attached (that is, a primary site that has child sites beneath it in the site hierarchy). A parent site can have primary or secondary sites attached to it.

PDF

See package definition file (PDF).

pragma statement

A line in a MIF file or event configuration file that indicates how the information relates to the information in a site database. See also MIF file.

primary site

A site that has its own SQL Server database to store the system, package, inventory, and status information for the site itself and the sites beneath it in the site hierarchy. It also has administrative tools that enable you to directly manage the site and the sites beneath it in the site hierarchy.

A primary site must be installed from the Microsoft Systems Management Server version 1.2 compact disc. When a primary site is initially installed, it is a standalone central site. Once a primary site is installed, you can use the SMS Administrator to integrate the new site (and any of its subsites) in the hierarchy of another SMS system.

program group (SMS program group)

A collection of program items within the Program Manager. You create program groups using program items defined by the Sharing properties of packages. From the packages, you choose the program items to include in the program group. You then assign program groups to LAN Manager user groups, NetWare user groups, and Windows NT global groups. Wherever the users in these groups log on, their assigned program groups appear in the Program Manager on the local computer. By choosing a program item, these users start the SMS network application for that item.

Program Group Control

A set of programs (APPCTL and APPSTART) on computers running Windows version 3.1 and Windows NT that enable users to run SMS network applications. The Program Group Control feature sets up and starts the SMS network applications so that the applications can be run over the network from distribution servers.

program item (package)

An object composed of an icon and the command line for running an SMS network application. A program item also contains other details about how the SMS network application should be started (such as running the application minimized). Program items are displayed to the user as icons contained within a program group that is assigned to a user group in which that user is a member. The user can use the program items to start SMS network applications. You define a package's program items in the package's Sharing properties.

promiscuous mode

A state in which a network adapter card detects all the frames that pass over the network.


Q

query

An SMS object that contains the criteria used to find objects in the site database. A query defines and stores the criteria used to identify the objects you want to find. By running a query, you search the inventory for the objects that match the query's criteria. The results are displayed in a Query Results window.

query criteria

The set of instructions used to search for the objects you want to find. When you run a query, the SMS system finds the objects that satisfy the query's criteria and displays them in a Query Results window.

query result format

An object that stores the format used to display the results of a query. A query result format enables you to select which attributes to display for the list of objects returned in the Query Results window. A format is specific to a single architecture. For example, a query format defined for an Employee architecture cannot be used to display computers, which may have a Personal Computer architecture.

Query Results window

A window that displays the results of a query using the specified query result format. A Query Results window displays all the objects that match the query's criteria.

You can modify the query and run it again by choosing the query bar. Note that any modifications you make to the query from a Query Results window do not affect the original query (which is stored in the database).


R

RAS Sender

See sender.

RAW file

A binary inventory file that is processed by the Inventory Processor into a binary MIF file.

relational operator (query)

Part of an expression (such as is equal to or is like) that defines how the specified value should be compared with the actual value stored for the specified attribute. See also expression (query).

remote control agent

A program (either USERTSR.EXE or USERIPX.EXE) that enables you to use the remote troubleshooting utilities to diagnose or control a client.

remote site

A site other than the current one.

remote troubleshooting utilities

Tools that allow you to directly control and monitor remote clients running MS-DOS, Windows version 3.1, and Windows for Workgroups version 3.11.

Remove Package From Server job

A job that removes a package installed on servers.

A Remove Package From Server job can remove the compressed package stored on the site server and the package source directory installed on specific distribution servers.

repeating job

A job with its Repeat option set to a time interval. (You set the Repeat option in the Job Schedule dialog box.) The SMS system measures the interval starting from the Start After time. For example, a job with a Repeat setting of Daily and a Start After setting of 8/1/93 10:00 P.M. will have its second repeat job activated after 8/2/93 10:00 P.M., the third at 8/3/93 10:00 P.M., and so on.

Run Command On Workstation job

A job that runs a package command at target clients.

A Run Command On Workstation job sends the source directory specified by the package's Workstations properties to target sites (and places them on specified distribution servers) and makes the package command available at target clients. At each target client, the user can run the package command by selecting the package command.


S

Scheduler

An SMS component (within the SMS Executive service) that detects pending jobs and creates auxiliary files that allow jobs to be processed. This includes jobs initiated by a user, such as a Run Command On Workstations job, as well as system jobs.

secondary site

A site that has no SQL Server database to store its system, package, inventory, and status information. Instead, it forwards inventory and status information to its primary site for processing and storage. It also does not have administrative tools for direct administration of the site — you must administer a secondary site through one of its parent sites (a primary site above the secondary site).

You install a secondary site by using the SMS Administrator at the primary site under which the new secondary site will be placed. A secondary site can only be created and configured from an immediate primary site. A secondary site cannot have subsites beneath it.

send

An action that is performed by a job when handling a package. Sending is the method used by the SMS system to transfer data and instructions for jobs between sites (limited sending also occurs within a site). When a job is activated by the Scheduler, the Scheduler compresses the data or instructions needed to complete the job and writes a send request for a sender to transfer the data or instructions. The sender transfers the data or instructions to the target site, where the Despooler handles or routes the data or instructions to the SMS services required to complete the job at that site.

send request file

A file with instructions that the sender uses to connect to a specified site and to transfer the specified data to the site.

sender

An SMS component (within the SMS Executive service) that is used by the SMS system to send instructions and data from one site to another (such as reporting inventory information or installing software on clients at another site). There are three types of senders: LAN Sender, RAS Sender, and SNA Sender. The RAS Sender and SNA Sender are divided into subtypes to support different means of communication.

SMS supplies three RAS Senders: MS_ASYNC_RAS_SENDER, MS_ISDN_RAS _SENDER, and MS_X25_RAS_SENDER. SMS supplies two SNA Senders: MS_BATCH_SNA _SENDER and MS_INTER_SNA_SENDER.

Share Package On Server job

A job that places files on servers and shares them, enabling users access to the files at each target site. A Share Package On Server job installs the package's Sharing source directory on target servers and shares that directory using the specified share and permissions.

This job can be to simply distribute and share a directory at a set of servers in a site, giving users access to a copy of the source directory files. Or it can be used to install the package so that the applications it contains can be set up as SMS network applications, letting assigned users run the package's programs over the network.

site

An SMS object that logically groups a set of domains into an administrative unit for managing computers. Every site has a site server.

When you configure a site, you select the domains that you want to include in the site.

There are two types of sites: primary sites and secondary sites.

When you set up an SMS system for your organization, you must have a primary site that serves as the central site.

site code

A three-character code that the SMS system uses to identify a site. Used as part of the addressing information for communicating between sites, the code for any site must be unique across the SMS system.

Site Configuration Manager

An SMS service that installs and maintains the SMS services at the site server and the SMS logon servers in the site. The Site Configuration Manager monitors all the SMS services on the site server and all the SMS logon servers to ensure that those servers are active and the SMS services are started.

site control file

An ASCII text file that contains the configuration for a site.

When a site is first created or the site properties are modified, the Hierarchy Manager creates a site control file with the proposed configuration for the site. The Site Configuration Manager reads this file to configure the site.

A site control file is also used by the Site Configuration Manager to report the current site configuration to the Hierarchy Manager, which uses the file to update the site configuration information stored in the site database.

site database

A Microsoft SQL Server database that stores system information (configuration and status) and the software and hardware inventory at a primary site. Every primary site must have a site database.

site group

An alias for a group of sites — that is, a shortcut for referring to multiple sites. Instead of referring to each site individually, you can include them in a site group and use the site group name. You can use a site group to limit a job to the sites in the site group. You can also use a site group to narrow down a query.

Site Reporter

At child sites, an SMS component (within the SMS Executive service) that detects a queue of Delta-MIFs containing inventory, job status, or event information, and creates a mini-job to send these files on to the parent site. The Site Reporter exists in both primary and secondary sites.

site server

A computer that contains the SMS components needed to monitor and manage the site, its domains, and its computers. Each site must have a site server.

SMS Administrator

The program used to administer the SMS system.

SMS client

A computer included in the SMS computer inventory. An SMS client is included in the computer inventory, receives packages for installation, and can run SMS network applications. In addition, the SMS system assigns the client an ID that is unique across the whole SMS system.

SMS logon server

A server added to the computer inventory of a site. An SMS logon server supports SMS configuration, inventory collection, package installation, and SMS network applications for the SMS clients in its domain. A site server is automatically added as an SMS logon server.

SMS network application

A computer program defined within a package and run over the network by individual users at clients. In the SMS system, SMS network applications are defined as program items within a package. You can assemble program items from any package into program groups. These program groups are then assigned to LAN Manager user groups, Windows NT Server global groups, or NetWare user groups. Wherever these users log on, they will see a program group that contains their assigned SMS network applications in the Program Manager on the local client.

SMS system database

See site database.

SNA Receiver

An SMS service that processes instructions and data sent by an SNA Sender. When you install an SNA Sender on a computer, the SNA Receiver is automatically installed with it.

SNA Sender

See sender.

subclause (query)

A set of expressions that can be logically treated as a single expression. You can explicitly specify that a subclause is a group. A group is surrounded by parentheses.

subsite

A site beneath another site in the site hierarchy.

system database

See site database.

system job

A job that transfers system instructions to other sites. System jobs are used to maintain a site or report event, status, or inventory data to other sites.


T

target clients

The computers where a package is installed by a Run Command On Workstation job. The target clients can be specified as a machine group, as the result of a query at the job's start time, or as all clients in the whole corporation, site, or SMS domain.

target sites

The sites where a job sends a package or performs an action. For example, when you create a Run Command On Workstation job, the target sites are the sites where the target clients are located.

trigger

A condition that sets off an alert when the condition is true. See also alert.


W

workgroup

A logical grouping of computers for browsing network resources. Windows NT, Windows for Workgroups, and Microsoft Workgroup Add-on for MS-DOS support workgroups.


About the Resource Guide

This guide includes the following chapters.

Chapter 1, "Microsoft Exchange Server Architecture," explains Messaging Application Programming Interface (MAPI) communication and the architecture of Microsoft Exchange Server and Microsoft Exchange Client.

Chapter 2, "Setup," describes the Microsoft Exchange Server and Microsoft Exchange Client Setup process. It also describes how to customize client and server installations.

Chapter 3, "Working with Microsoft Exchange Server," describes how to maintain Microsoft Exchange Server and Microsoft Exchange Client. It includes information about backing up and restoring servers, logging download information, customizing details templates for languages, and setting up roving and remote users.

Chapter 4, "Public Folders," describes how to plan, set up, and replicate public folders.

Chapter 5, "X.400 Connector," explains how the Microsoft Exchange Server X.400 Connector is used to establish an X.400 messaging route.

Chapter 6, "Addressing and Routing," describes how Microsoft Exchange Server messages are addressed and routed.

Chapter 7, "Security," contains information about how advanced security works and describes how to avoid Internet security breaches.

Chapter 8, "Optimizing Performance," discusses how to optimize the performance of Microsoft Exchange Server by balancing hardware and software resources.

Chapter 9, "Troubleshooting," provides information about troubleshooting problems with Microsoft Exchange Server and Microsoft Exchange Client.

Appendix A, "Creating an .Ini File for Microsoft Exchange Server Batch Setup," describes the format of an .ini file that you can run with Microsoft Exchange Server Setup in batch mode (Setup /q).

Appendix B, "System Management Checklist," provides checklists for daily, weekly, monthly, and periodic maintenance tasks to ensure that your Microsoft Exchange Servers are operating efficiently.

Appendix C, "Performance Monitor Chart Views," describes the preconfigured Windows NTâ Performance Monitor chart views included with Microsoft Exchange Server.

Appendix D, "Setting Permissions," explains how you can use permissions on directory objects and public folders to restrict or grant access. It also describes the permissions that are needed to administer Microsoft Exchange Server.

Appendix E, "Tools," contains information about Microsoft Exchange Server tools that can be used to troubleshoot problems in your organization.


Conventions in This Manual

The following table summarizes the typographic conventions used in the Microsoft Exchange Server Resource Guide.

Convention

Description

bold

Menus and menu commands, command buttons, property page and dialog box titles and options, command-line commands, options, and portions of syntax that must be typed exactly as shown.

Initial Capitals

Names of applications, programs, and named windows.

Italic

Information you provide, terms that are being introduced, and book titles.

KEY+KEY

Key combinations in which you press and hold down one key and then press another.

Monospace

Examples, sample command lines, program code, and program output.

SMALL CAPITALS

Names of keys on the keyboard.


Introduction

Welcome to the Microsoft Exchange Server Resource Guide. This guide is designed for people who are, or who want to become, expert users of Microsoftâ Exchange Server and Microsoft Exchange Client.

The Microsoft Exchange Server Resource Guide is a technical supplement to the documentation included as part of the Microsoft Exchange Server product and does not replace that information as the source for learning how to use Microsoft Exchange Server.


Chapter 1 MS Exchange Server Architecture

Understanding the architecture of the Microsoft Exchange Server and the Microsoft Exchange Client and how they communicate can help you maintain and troubleshoot your Microsoft Exchange Server organization.

For more information about Microsoft Exchange Server architecture, see the Microsoft Exchange Server Programmer's Reference or the MAPI Programmer's Reference.


Organizations and Sites

To simplify administration and provide scalability, Microsoft Exchange Server is based on organizations and sites. An organization is the largest administrative unit in Microsoft Exchange Server. It contains all the servers that provide the messaging functionality for a company.

Typically a company has only one organization that consists of one or more connected sites. A site is a group of Microsoft Exchange Server computers that share the same directory information and can communicate over high-bandwidth, permanent, and synchronous network connections. Sites can also contain Microsoft Exchange Client computers. For example, if your organization has several offices in different cities, the clients and servers for each office can be in different sites.

You can connect sites by using a variety of methods, such as wide area networks (WANs), the Internet, or even dial-up lines. Connecting sites enables users in different locations to send messages quickly and efficiently and to exchange information by using public folders. It also allows you, the administrator, to manage servers from remote locations and ensure that information in all sites is the same.

You can manage your organization and sites by using the Administrator program, which can be run on a Windows NT Server or Windows NT Workstation computer. You can use the Administrator program to view and configure all the objects in your organization, such as sites, servers, connections, and message recipients.


Integration with Windows NT Server

As an application that runs on Windows NT Server, Microsoft Exchange Server takes advantage of important features, such as security, provided by the operating system. Although domains and sites are unrelated (domains are specific to Windows NT Server, and sites are specific to Microsoft Exchange Server), resources in sites rely on domains to perform essential security operations. For example, to prevent unauthorized users and services from gaining access to Microsoft Exchange Server resources, domains authenticate users when they log on to their mailboxes. They also validate Microsoft Exchange Server services.

All Microsoft Exchange Server components run on Windows NT Server as multithreaded Windows NT services. Just as users must be authenticated by a domain to log on to a client computer, Microsoft Exchange Server services must be authenticated by a domain to run in the site. Microsoft Exchange Server services, such as the system attendant, the information store, and the directory, use a type of user account called a service account. A service account is a Windows NT user account that services use to gain access to the system. For example, the directory service uses the site's service account to read and write to the local directory and directories on other servers.

A site's service account must be authenticated by the domain that contains the Microsoft Exchange Server computers or by a trusted domain in order for Microsoft Exchange Server services to interact. To send mail between two servers in a site, the message transfer agent (MTA) on one server should use the same service account as the MTA on the other server. Each site can have only one service account.


Communication Between the Client and Server

Microsoft Exchange Server services communicate with each other as client and server processes by using remote procedure calls (RPCs). RPC is an industry standard protocol for client/server communication. With RPC, clients and servers can communicate with one another efficiently and independently of the network type. An RPC is a routine that transfers functions and data between client and server processes. If the client and server are running on the same computer, RPCs are mapped to local procedure calls (LPCs), which are much faster than RPCs.


Server Architecture

The Microsoft Exchange Server architecture is composed of modular components that provide integrated and reliable messaging, scheduling, and information-sharing functions. The Microsoft Exchange Server core and optional components maintain address and message databases, and log transactions. They also allow you to connect with other Microsoft Exchange Server computers and foreign systems.


Core Components

The following Microsoft Exchange Server core components are installed during Setup and must be running on the server at all times:

  • Directory
  • Information store
  • MTA
  • System attendant

The following illustration shows how the core components interact. The directory, information store, and MTA process requests from the client and each other. The system attendant maintains server operation and performs key functions, such as generating e-mail addresses for new recipients.

The core components perform tasks similar to those of your local post office. When you use Microsoft Exchange Server to send a message, the message is first delivered to a central postoffice called the information store. The information store then determines where the message should be delivered by looking in the directory, which is like an address book. Then, the mail carrier or MTA delivers the message. The system attendant is a background process that makes sure the system runs smoothly and mail is routed correctly.

Directory

The directory stores all the information about a Microsoft Exchange Server organization, such as addresses, mailboxes, distribution lists, public folders, and configuration information about sites and servers. It provides a single, central location where users and applications can look up and configure information about any object. The directory also generates the Address Book, which users can use to address messages or look up information about other users. The Address Book contains all the recipients in the organization and is organized into lists, such as the global address list and the personal address book (PAB).

All information about an organization is stored as configurable elements or objects in a database. Each object in an organization is represented in a hierarchical tree structure and has a set of attributes or properties. You can customize your organization by changing the properties on directory objects in the Administrator program. For example, you can set message storage limits on mailboxes by setting properties on the information store object for a server. You can also specify who has permission to make changes to directory objects. For information about how to change properties on objects in the Administrator program, see the Microsoft Exchange Server Administrator's Guide.

The directory makes the following tasks possible:

  • Users can access the directory to find information about Microsoft Exchange Server users, custom recipients, and other recipients of electronic mail, such as distribution lists and public folders.
  • Administrators can centrally manage all objects in a site by using the Administrator program or a custom application that calls the Microsoft Exchange Server directory functions.
  • Developers of third-party applications can write custom applications and add-on services that can store configuration information and make it available through an extension to the Administrator program as a custom property page.
  • Microsoft Exchange Server services, such as the information store, use the directory to look up information that is needed to provide a specific service. For example, the system attendant looks up connector configuration information to build the routing table. The MTA also looks up a user's address in the directory and uses it with the routing table to route a message.

The directory is automatically replicated between servers in a site to ensure that all servers have the same information. Between sites, the directory is replicated by directory bridgehead servers according to a schedule you set in the Administrator program. Each site has one or more directory bridgehead servers that are responsible for keeping the site's directory synchronized with the directory in other sites.

Keeping the directory up-to-date is important. If directory information is out of date, messages may not reach their destination. For example, if a new mailbox is added to a server, servers in another site won't know the new mailbox exists until the directory is replicated to the other site. Also, users can't send messages to the new mailbox until the directory on the mailbox's home server has been replicated. For more information about directory replication, see the Microsoft Exchange Server Administrator's Guide.

How the Directory Works

The directory uses a memory cache to minimize the time required to process requests and a transaction log buffer to minimize wait time while read and write requests are logged. The directory's memory cache increases performance by maintaining the most recently requested information in memory, rather than reading from the disk for every request.

When an address is created or modified, the directory logs the transaction in the transaction log file. The log is written sequentially to increase performance. If the server fails before changes are written to the database, the directory uses this log to restore the changes. The following illustration shows how the directory uses the cache, directory database, and transaction logs.

When the directory receives an address request, it:

  • Checks to see whether the address is already in memory (the buffer).
  • Accesses the directory database for the address, if the address is not already in memory.
  • Returns the requested address or a "not found" message to the requesting information service.

When the directory receives an address change, it:

  • Logs the change in the directory transaction log.
  • Writes the change to the memory buffer.
  • Returns a confirmation to the user who requested the change.
  • Writes the change to the directory database.

The directory can be accessed by users, administrators, and applications.

Users

Users can access the directory by using mailboxes, distribution lists, custom recipients, and public folders, all of which are addressable objects.

Administrators Administrators can access the directory through the Administrator program to:

  • Create or delete most types of individual directory objects.
  • Modify the attribute values of directory objects.
  • Perform certain import/export operations.

In most cases, you can perform these tasks on one object at a time. After a directory object has been created, you can edit its attributes in the following ways.

  • Using property pages, which display the most commonly accessed attributes.
  • Using raw mode, which displays all of the available attributes for that object.

Applications The directory can be accessed by other applications running on Windows NT Server and custom applications developed for Microsoft Exchange Server. They access the directory to:

  • Manipulate a large number of directory objects; for example, during administration of custom add-on services.
  • Synchronize the Microsoft Exchange Server directory with directories of foreign systems.
  • Automatically update Windows NT user accounts when their associated directory objects (such as mailboxes) are updated.
  • Look up routing tables, which are stored in the directory.

Information Store

The Microsoft Exchange Server information store maintains and accesses the message database for Microsoft Exchange Client users on the local server. The information store is visible as users' Inboxes and folders. It can store all types of information, including word processing documents, spreadsheets, and messages.

The information store has the following subcomponents:

  • A private information store that contains user mailboxes.
  • A public information store that contains public folders.

A server can have both a private information store and a public information store, or it can be dedicated to providing specific services, such as mailboxes or public folders. You can make a server a dedicated mailbox server by installing only the private information store, or you can make it a dedicated public folder server by installing only the public information store. You can significantly improve performance for users accessing the information store by dedicating a server to one of these functions.

How the Information Store Works

The information store's memory cache provides increased performance by maintaining the most recently requested messages in memory, rather than reading from the hard disk for every request. This buffer allows a message that has been read or modified recently to be accessed quickly by subsequent requests. It also allows the information store to hold changes to the database in memory during busy periods and write to the database during slow periods.

When a message is created, modified, or deleted, the information store records the transaction in a log file. The log is written sequentially to increase performance. If the server fails before changes are written to the database, the information store uses this log to restore those changes.

The following illustration shows how the information store uses the cache, database, and logs.

The information store maintains information in the public and private information databases. It uses single-instance storage of messages so a message sent to many recipients is stored only once on the server. This conserves disk space because the information store doesn't need to store a copy for every message recipient.

When the information store receives a request to access a message, it:

  • Determines whether the message is already in memory (the buffer).
  • Accesses the message database for the message, if the message is not already in memory.
  • Returns the requested message or a "not found" message to the requesting information service.

When the information store receives a message from a user on the local server to send, it:

  • Resolves individual addresses.
  • Logs the message received in the information store log.
  • Queries the MTA and directory to expand distribution lists, if a message is addressed to users on the same server.
  • Writes the message to the user's Inbox and notifies the Microsoft Exchange Client.
  • Applies rules the recipient has set as the message is delivered to the user's Inbox.
  • Forwards the message to the MTA for routing, if a recipient is on another server.

The information store can be accessed by users, administrators, and applications.

Users

Users can access information store objects, such as messages, and private and public folders.

Administrators

Administrators can access the information store through the Administrator program to:

  • Create or delete mailboxes.
  • Modify the attribute values of information store objects.
  • Create and modify permissions on public and private folders.

Applications The information store accesses and is accessed by other applications running on Windows NT Server. The information store accesses the directory and MTA as follows:

  • Requests address information from the directory to resolve addresses or expand distribution lists.
  • Retrieves messages requested by users.
  • Forwards messages received for other Microsoft Exchange Servers to the MTA for routing.
  • Forwards messages for foreign gateways through the appropriate connector for delivery.

MTA

The MTA routes messages between Microsoft Exchange Servers in a site and to MTAs in other sites. It also expands distribution lists. The MTA uses a memory cache and message tracking log for performance and reliability. The following illustration shows the MTA architecture.

When the MTA receives a message, it:

  • Secures the message in the message transfer database and queues the message until it can be sent.
  • Queries the directory to determine where the message should be routed.
  • Routes the message to the MTAs of the recipients' servers or to the information store for delivery through a connector.
  • Deletes the message after it is routed.

The MTA uses two types of X.400 interfaces when routing messages:

  • The MA Interface is used between X.400 clients and X.400 MTAs. The MTA uses this interface to communicate with the other Microsoft Exchange Server components.
  • The MT Interface is used between X.400 MTAs. The MTA uses this interface to communicate with other Microsoft Exchange Server MTAs and X.400 compatible MTAs.

The MTA can be accessed by administrators and applications.

Administrators

Administrators can access the MTA through the Administrator program to:

  • Set the MTA name or password.
  • Set limits on message size.
  • Recalculate the routing tables.
  • Expand distribution lists locally.

Applications The MTA accesses and is accessed by other applications running on Windows NT Server. The MTA accesses the directory, information store, and system attendant as follows:

  • Requests address information from the directory when it needs to resolve addresses or expand distribution lists.
  • Sends log entries to the system attendant for message tracking.
  • Delivers messages received from remote MTAs to the local information store.
  • Routes messages from the local information store to remote MTAs.

System Attendant

The system attendant is a general maintenance service. It rebuilds the routing tables, manages the server and link monitors, and sets up advanced security for Microsoft Exchange Client users.

The system attendant can be accessed by administrators and applications.

Administrators

Administrators can access the system attendant through the Administrator program to set time limits for keeping message tracking logs.

Applications The system attendant accesses and is accessed by other applications running on Windows NT Server. The system attendant accesses the directory, MTA, and key management component as follows:

  • Requests address information from the directory when it needs to resolve addresses or expand distribution lists.
  • Builds routing tables for the MTA.
  • Generates e-mail directory addresses for new recipients.
  • Checks the consistency of directory replication.
  • Stores and manages digital signatures and encryption information for a mailbox during configuration of advanced security.
  • Sends and receives mail for the link monitor.
  • Initiates and maintains link and server monitors.


Optional Components

You can install optional components to benefit from added features, such as connectivity to other messaging systems and advanced security. For example, if your users need to send messages to Internet users, you can install the Internet Mail Connector. If you have Microsoft Schedule+ users on both Microsoft Mail for PC Networks and Microsoft Exchange Server, you can install the Schedule+ Free/Busy Connector so users can view free and busy times.

The following optional components can be installed on a Microsoft Exchange Server computer.

Internet Mail Connector

Enables users on Microsoft Exchange Server to send messages to and receive messages from users on the Internet. The Internet Mail Connector can also be used to connect sites over a simple mail transport protocol (SMTP) backbone.

Microsoft Mail Connector

Enables users on Microsoft Exchange Server to send messages to and receive messages from users on Microsoft Mail for PC Networks and Microsoft Mail for AppleTalk Networks. The Microsoft Mail Connector includes all components required to connect to Microsoft Mail postoffices, including the directory synchronization component and the Schedule+ Free/Busy Connector.

X.400 Connector

Can be configured to connect sites with Microsoft Exchange Server, or to route messages to foreign X.400 systems. The X.400 Connector conforms to the 1984 and 1988 CCITT X.400 standards. For more information, see Chapter 5, "X.400 Connector."

  • Key Management Manages security information used for digitally signing and encrypting messages sent between users within an organization. For more information, see Chapter 7, "Security."

The following illustration shows how the optional components interact with the core components.


Client Architecture

The Microsoft Exchange Client user interface is designed to operate as a universal inbox where users can access information regardless of the information's source or format. The key component is the Microsoft Exchange Client Viewer, which provides the Inbox interface. Schedule+ and Microsoft Exchange Forms Designer are client applications that expand and complement the Viewer, adding scheduling and electronic forms.

The Microsoft Exchange Client is based on Messaging Application Programming Interface (MAPI), which is a standard interface that defines a modular architecture. MAPI enables users to add and remove applications and information services on the Microsoft Exchange Client. Users can configure the information services they want to use in their messaging profile. In addition, third-party vendors can develop MAPI-compliant applications and services that can be used with the Microsoft Exchange Client to provide an unlimited number of services.

Schedule+

Schedule+ uses the messaging capabilities of the Microsoft Exchange Client to send meeting requests and updates. Personal schedule information for each client is maintained in two places: in a schedule (.scd) file on the user's local disk and in a hidden private folder in each user's private information store. Another file, a hidden public folder on the server, maintains free and busy information for all users so it's available to everyone in the site.

Forms Designer

The Forms Designer is a tool for creating custom electronic forms that automate business processes and provide a structure for posting and viewing specific information. For example, you can use the Forms Designer to create a purchase requisition or expense report form that users can use instead of conventional paper forms. For more information about Forms Designer, see the Microsoft Exchange Server Application Designer's Guide.

Optional Information Services

MAPI enables information services, such as message stores and address books, to be added to the Microsoft Exchange Client. For example, users can store messages on their local disk by specifying personal folder (.pst) files in their messaging profile. The following optional information services can be used with the Microsoft Exchange Client.

Personal address book (.pab) file

Stores frequently used addresses from any address list, as well as custom recipients and distribution lists that the user defines. Users can create a personal address book and store it on either a file server or their disk.

Personal folder (.pst) file

Stores the user's personal folders and can be used to receive and deliver mail. This file can be stored either on a file server or on a user's disk.

Offline folder (.ost) file

Stores a snapshot of public and private folders so that remote users can use mailbox folders and favorite public folders while working offline. When the user connects to the server again, messages the user has sent or posted are automatically synchronized with the server folders.


Chapter 2 Setup

When you set up Microsoft Exchange Server, it's helpful to understand how Setup works so you can troubleshoot problems or customize your installation. If you understand how Setup works, it's easier to trace the cause of problems related to Setup. Understanding Setup also makes it possible for you to customize your installation quickly and easily so your client and server configurations suit your organization's needs. For example, you can run Setup unattended using customized settings or create default client messaging profiles.


Server Setup

The way you set up Microsoft Exchange Server varies depending on whether you are installing it for the first time or adding and removing components such as Microsoft Schedule+.

The table on the following page describes important files used during Setup.

Caution

You should not modify files used during Setup because doing so may result in unpredictable behavior.

File type

Description

.ins files

Server Setup reads installation files to create core services, directories, and processes; share directories; and modify the registry. These files are also used to perform a number of maintenance tasks such as adding Windows NT Performance Monitor counters. Most components have an associated .ins file. The most important installation file is the Server.ins file.

.uns files

Server Setup reads uninstallation files to remove previously installed components. Every .ins file has a corresponding .uns file that is run when you select the Remove All or Add/Remove option during Setup. To remove a component, the component's corresponding .uns file must be available.

.scr files

Script files are similar to installation files. Setup reads the .scr files and follows the instructions contained in the file. For example, if something goes wrong during Setup and services need to be stopped, Setup runs the Stop.scr file.

Server.inf

Server Setup reads this file when it copies files to the server's disk. This file contains a list of all files that are installed and where to install them.

Setup.log

Setup creates this log file when Setup is initialized. It is used to record all events that occur on the server during Setup. You can refer to this file if you encounter problems during Setup.

Your server may have two Setup.log files: one log file is created in the system partition the first time Microsoft Exchange Server is installed, and a second log file is created in the Exchsrvr directory the next time Setup is run. If there are two log files on the server when Setup is run, Setup appends the file in the Exchsrvr directory.


New Server Installation

When you install Microsoft Exchange Server, Setup gathers information including your organization name and site, the service account name and password, and whether the server is creating a new site or joining an existing site. Then Setup does the following:

  • Installs core components.
  • Installs optional components.
  • Performs directory replication with other servers in the site.

If you encounter problems during or after you've run Setup, you can use the following information to help you find solutions.

Core Components

During the first installation phase, Setup installs core components such as the system attendant, the directory, the information store, and the message transfer agent (MTA).

Validating the User Account and Service Account

Setup first verifies that the account of the user who is currently logged on is valid in the Windows NT Server domain and has Administrator permissions for the Site and Configuration objects. Setup also verifies that the service account and password used to install Microsoft Exchange Server are valid in the domain. This prevents an unauthorized server from being installed in a site.

In general, the way Setup determines the service account varies depending on whether the server is creating a new site or joining a site. When a server is installed in a new site, the account of the user who is currently logged on is used as the default service account. When a server is installed in an existing site, Setup looks in the registry of the remote server and uses the same service account for the new server.

Setup grants the following rights to the service account on the local computer if the service account doesn't already have them.

Right | Description
Logon as a service | Enables Microsoft Exchange Server services to use this service account for authentication in the domain.
Restore files and directories | Enables the information store and the directory to be restored from backup if necessary.

Copying Files and Installing Core Components

Once the user account and service account have been validated, Setup reads the Server.inf file and copies files to directories on the local disk according to the components you selected during Setup. Setup then reads the Server.ins file in the directory that Setup is run from. This file instructs Setup to create shared file directories. It also installs core services and updates the server's registry by adding permissions for registry items. Setup then starts the system attendant and directory services.

Building the Directory and Initiating Directory Replication

The next step in the process is installing the directory. Setup provides the directory with the server's computer name and the organization name and site that the new server is creating or joining. Once the names for the organization and site objects have been added to the directory, they can't be changed; however, you can change their display names after Microsoft Exchange Server has been installed.

The process for updating the directory with the organization and site name is different depending on whether the server is in a new site or joining an existing site. If the server is being installed in a new site, the organization and site names that you specified are added to the directory. If the server is joining an existing site, the server connects to another server in the existing site. It reads the names from the remote server's directory that you specified earlier in the process.

To complete the process of building the directory, Setup also performs the following:

  • Sets permissions on directory objects.
  • Initiates directory replication if the server is joining an existing site. To prevent directory conflicts when a server is added to an existing site, Setup notifies the server's directory that it shouldn't replicate with other directories in the site until the new directory is completely built. This ensures the objects in the new directory are the correct version.
  • Adds objects to the directory for additional components, such as the information store and the MTA, and modifies existing objects.
  • Installs templates into the directory.

Few directory operations occur on the new server that is joining a site. Setup modifies the directory on the remote server that you specified during Setup, and then the modified directory is replicated to the new server. If Setup fails while the directory is being installed, directory information about the new server can still exist on the remote computer until it's deleted from the remote server's directory. The following illustration shows how the directory is built and how replication is initiated.

Starting Remaining Core Services and Updating the System

Setup then starts any remaining core services such as the information store and the MTA. It also adds program items to the Microsoft Exchange Server program group and updates the registry.

Optional Components

After core components are installed and started, Setup installs the optional components that you selected, such as connectors and the Administrator program. The optional components are installed the same way as core components; however, the services for optional components must be started manually. Setup performs the following tasks to install optional components:

  • Reads the installation (.ins) file for each component. The .ins files instruct Setup to perform tasks such as installing services and modifying the registry.
  • Updates the directory with information about the component.
  • Adds program items to the program group and updates the registry.

Directory Replication

While Setup completes, the directory is fully replicated asynchronously in the background. Information, such as user accounts, that was not replicated earlier during Setup, is replicated from the remote server to the new server at this time.


Server Maintenance Installation

Once you've installed Microsoft Exchange Server, you can run Setup again to add or remove components as needed. For example, you may decide to add a connector on your server. When you run Setup, it detects whether Microsoft Exchange Server is already installed on the computer. If it is, Setup starts maintenance installation. Maintenance installation includes options for Add/Remove, Remove All, and Reinstall.

Adding or Removing Components

When you add components by selecting the Add/Remove option, Setup runs the installation (.ins) file for each selected component.

When you remove components by selecting the Add/Remove option or the Remove All option, Setup performs the following:

  • Deletes one or more specified components from the system by running the uninstallation (.uns) file for each component. If the Remove All option is selected, all Microsoft Exchange Server components are deleted.
  • Removes the service for each component and deletes references to the component in the registry and directory.

Reinstalling Microsoft Exchange Server

You can use the Reinstall option to upgrade Microsoft Exchange Server to a later version or to restore registry settings if the registry becomes corrupted. To update Microsoft Exchange Server, Setup performs the following.

  • Checks the version of the existing installation.
  • Overwrites the appropriate files.
  • Modifies the registry entries.
  • Sets values in the directory.

Setup does not overwrite templates because they can be customized by users. The database files for the information store or directory are not modified.


Running Setup Unattended

You can customize your server installation by running Setup unattended using customized default settings that you specify in a Setup.ini file. If you're installing Microsoft Exchange Server on multiple computers for the first time and want to use the same configuration on all servers, you can run the Setup program in unattended batch mode.

Running batch mode Setup is useful if you need to install Microsoft Exchange Server quickly and don't want to be prompted to enter additional information. Batch mode Setup (Setup /q) can be used with an .ini file containing configuration settings so you can install Microsoft Exchange Server without user input. For example, you can use batch mode Setup to install Microsoft Exchange Server in offices that don't have full-time administrators who can set up the servers.


Creating an .Ini File for Batch Setup

Before you can run batch mode Setup, you must create an .ini file containing default installation settings. In the .ini file, you can specify preferences, such as the installation directory, the organization name, and the components, that will be installed. Using an .ini file is equivalent to selecting options in dialog boxes during Setup; however, the .ini file provides additional options so you have more control over your installation.

You can use any text editor to create an .ini file with any name. Several .ini file examples are included on the Microsoft Exchange Server compact disc in the Support\Samples\Setup directory. The following example shows the format of the .ini file.

[Paths]
;Where the server will be installed if selected.
ServerDest= C:\Exchsrvr

;Where Admin will be installed if selected. This entry is optional.
AdminDest= C:\Exchsrvr

For more information about .ini file settings, see Appendix A, "Creating an .Ini File for Microsoft Exchange Server Batch Setup."


Running Batch Mode Setup

To run batch mode Setup once you've created an .ini file, type the following at the command prompt:

Setup /q filepath

where filepath is the path and file name of the .ini file.


Client Setup

You can install the Microsoft Exchange Client locally (from a client installation point or floppy disks) or from a network share.


New Client Installation

Most Microsoft Exchange Client files are stored in several compressed cabinet (.cab) files until they are installed. When Setup is run, the cabinet files are uncompressed and the files are copied to the client's disk or a network server. Knowing where the Microsoft Exchange Client files are stored when they are installed can be useful information if you need to troubleshoot a problem. For example, if the Microsoft Exchange Client won't start and it's running from a network server, the server containing the Microsoft Exchange Client files may be down. The location of the files depends on whether:

  • The Microsoft Exchange Client is run from the local disk or from a network share.
  • The operating system for the client computer is run from the local disk or from a network share.

The Microsoft Exchange Client installs configuration files, application files, and Messaging Application Programming Interface (MAPI) files. Configuration files (including .ini files, spelling DLLs that Microsoft Exchange Client and other applications share, and information about forms) are copied to and run from the Windows directory or the user's home directory on the local disk or another location on a network server where user files are stored. The following table describes where application files and MAPI files are copied to or run from depending on the Microsoft Exchange Client computer's configuration.

 | Application Files |  | MAPI System Files
 | Copies to Exchange directory | Runs from network share | Copied to local Windows System directory | Runs from Windows System directory on operating system network share
Local operating system and client | X |  | X |
Local operating system and shared client |  | X | X |
Shared operating system and local client | X |  |  | X
Shared operating system and client |  | X |  | X

Local Installation

Setup uses the following process when installing the Microsoft Exchange Client to the local disk from a client installation point or floppy disks. If you encounter problems during Setup, you can use this information to help you troubleshoot. The operating system is running locally.

1. Reads the Setup.lst file in the client installation point to determine which files must be copied to the local disk. The Setup.lst file also instructs Setup to create a temporary, hidden directory for these files on the local disk that is called ~Mssetup.t\~Tmpjnk.t. The cabinet (.cab) files are uncompressed as they are copied to the temporary directory.

2. Reads the Exchng.stf file that was copied to the temporary directory and gathers the user's installation information. This file contains information such as the name of the user's organization and whether the installation is local or shared. By default, Setup obtains the user's name and organization from the registry or, depending on the operating system, the Win.ini file.

3. Copies files to the local disk as described in "New Client Installation" on the preceding page.

4. Writes the Exchng.stf file to the Exchange directory. Edits the registry or Win.ini file to indicate the location of the Exchng.stf file. Deletes the temporary directory.

5. If a Default.prf file exists in the client installation point, Setup copies the file to the Windows directory and runs the automatic profile generator (Newprof.exe) to create a default profile. If a default profile does not exist, the Microsoft Exchange Client runs the Profile Wizard the first time the client is run.

Shared Installation

To set up a network share and install Microsoft Exchange Client, you must first create the share by running Setup with the /a option. Then, you or the user can run Setup to install the Microsoft Exchange Client from the network share. If you encounter problems during Setup, you can use the following information to help you isolate the cause of the problem.

How a Network Share Is Created

Setup /a creates a network share depending on whether the operating system on the computer setting up the share is running from a network share or from a local disk.

  • If the operating system is local, Setup copies all files from the client installation point to the new network share. Cabinet (.cab) files are uncompressed as they are copied to the new location.
  • If the operating system is shared, Setup copies all application files to the new network share. Cabinet (.cab) files are uncompressed as they are copied to the new location. Setup also installs MAPI system files to the Windows System directory on the operating system share.
How Microsoft Exchange Client Is Installed from a Network Share

After you've created the network share, you can install Microsoft Exchange Client to run from the network share. The Setup process to install from a network share is similar to installing to a local disk, with the following differences:

  • Files required for Setup are not copied to a temporary directory as they are during a local installation.
  • Files are copied to directories on either the local disk or the network. For more information, see "New Client Installation" earlier in this chapter.


Client Maintenance Installation

Once you've installed Microsoft Exchange Client, you can run Setup again to add or remove components as needed. For example, you can remove online Help for the Microsoft Exchange Client or add Schedule+.

Setup relies on the Exchng.stf file to perform maintenance installations, which include the Add/Remove, Remove All, and Reinstall options. Setup reads the Exchng.stf file to determine which components are already installed. Then Setup writes information to the file, identifying which components should be added or removed. If a component is removed, Setup removes all references to it from the system.


Customizing Your Client Installation

You can customize the Microsoft Exchange Client in the following ways:

  • Using the Setup Editor to modify default Setup options.
  • Configuring default messaging profiles using the automatic profile generator (Newprof.exe).
  • Running Setup unattended from the command line or by using Microsoft System Management Server (SMS).
  • Changing the remote procedure call (RPC) binding order to improve client performance.


Using the Setup Editor

If you want to set up the Microsoft Exchange Client on many computers in your organization and use the same configuration on all clients, you can customize Setup options. When you run Setup, the Microsoft Exchange Client is installed with the settings you specify.

You can use the Setup Editor to change default Setup options by editing the Exchng.stf file located in the client installation point. You can specify options such as how users will be notified of new mail, the RPC protocols binding order, and which information services are installed on the client. You can also use the Setup Editor to specify default profile settings that can be used with the automatic profile generator (Newprof.exe) during Setup. These settings are stored in a Default.prf file created by the Setup Editor.

Caution

Use the Setup Editor to edit the Exchng.stf file. Editing the file manually can have unpredictable results because the file has a unique way of tracking whether components have been installed.


Configuring Default Messaging Profiles

Microsoft Exchange Server provides a tool called the automatic profile generator (Newprof.exe) that can be used as an alternative to the Profile Wizard. If you use Newprof.exe, users don't need to create their own profiles using the Profile Wizard after Microsoft Exchange Client has been installed. It creates a default messaging profile with settings that you have specified. This process is transparent to the user.

Newprof.exe can be run during Setup or from the command line. It uses a .prf file to determine the settings for the new profile. If there is no default profile in the user's home directory and a .prf file is present, Newprof.exe creates a profile based on the information that you specified in the .prf file.

You can run Newprof.exe with a .prf file from the command line with a variety of distribution mechanisms such as SMS, logon scripts, and e-mail. If you use it with logon scripts, Newprof.exe can be used to create default profiles for roving users when they log on to a new computer. Roving users are users who log on to the Microsoft Exchange Client from different computers in an organization.

Automatically Creating Profiles for Roving Users

Many users need to access their e-mail from different Microsoft Exchange Client computers. For example, a roving user can have two offices in two different locations. You can make it easier for a roving user to log on to a new Microsoft Exchange Client computer by using the automatic profile generator to create a default profile. If you preconfigure a default profile, roving users don't need to create a profile using the Profile Wizard every time they log on to a new client computer because the automatic profile generator creates one if needed.

To create profiles for roving users automatically, you can create a .prf file with the user's logon name and home server defined. You can also configure the logon script to verify that a profile does not exist for that user on the computer. If the computer doesn't already have a profile defined for the user, then the logon script calls Newprof.exe. Newprof.exe uses the .prf file in the user's home directory to create a new profile.

For more information about roving user support, see Chapter 3, "Working with Microsoft Exchange Server."

Using Newprof.exe with a .Prf File

You can use the Setup Editor or any text editor to specify settings in the .prf file. The .prf file can be in the client installation point or the user's home directory. If Setup is used to run Newprof.exe, the file must be named Default.prf or it will be ignored. To use a different name, you can run Newprof.exe from the command line as follows:

Newprof.exe -p filepath

where filepath is the path and file name of the .prf file.

You can use the sample Template.prf file provided with the Microsoft Exchange Client to create a customized .prf file.

Creating a .Prf File

Some of the most common entries in a .prf file are described in the following table. For a list of entries in a .prf file and their formats, see the sample Template.prf file.

Entry | Description | Value
MailboxName= | The name of the Microsoft Exchange Server mailbox. | The user's name
HomeServer= | The name of the Microsoft Exchange Server computer where the user's mailbox is located. | The server name
OfflineFolderPath= | The location of the offline (.ost) folder file. | The path and file name
PathToPersonalAddressBook= | The path to the personal address book (.pab). | The path and file name
EmptyWastebasket= | Whether to empty the Deleted Items folder when quitting. | True or false
GenReadReceipt= | Whether to generate a read receipt. | True or false
GenDeliveryReceipt= | Whether to generate a delivery receipt. | True or false
SaveSentMail= | Whether to save sent messages. | True or false

If the default profile's user name is not specified in the .prf file, Newprof.exe obtains the user's name from the registry or the Win.ini file. If this information is not available, the system prompts for a name when the user logs on to the client.


Running Setup Unattended

There are two options that you can use to install the Microsoft Exchange Client quickly on several computers. You can distribute the Microsoft Exchange Client by running Setup from the command line or by using SMS.

Running Setup from the Command Line

There are several command-line parameters that you can use to perform an unattended batch mode installation. Running Setup from the command line is useful if you need to install the Microsoft Exchange Client quickly and don't want to be prompted to enter additional information. The following parameters can be used for batch Setup. These parameters are case-sensitive.

Command-line parameter | Description
Setup /Q | Installs the Microsoft Exchange Client using the Typical option. This cannot be used with MS-DOSâ or when installing a shared installation of the client.
/N "name" | The user's name (not case-sensitive).
/O "organization" | The organization name (not case-sensitive).

For example, typing the following at the command line installs the Microsoft Exchange Client for a user named Maria Black without prompting for additional information.

Setup /Q /N "Maria Black"

You can use the following command-line parameters to perform unattended maintenance installations. Like batch mode Setup, these parameters are useful if you need to reinstall, remove, or restore the Microsoft Exchange Client quickly and don't want to be prompted to enter additional information. These parameters are case-sensitive and can't be used together.

Command-line parameter | Description
Setup /R | Reinstalls the Microsoft Exchange Client.
Setup /U | Removes all Microsoft Exchange Client components.
Setup /Y | Restores the Microsoft Exchange Client default settings.

Using SMS to Distribute the Microsoft Exchange Client

If you use SMS to install applications on clients in your network, you can also use SMS to distribute the Microsoft Exchange Client software. SMS makes it easier to install Microsoft Exchange Client on many computers without user input. SMS packages (.pdf files) for installing the Microsoft Exchange Client are provided with the Microsoft Exchange Client software. SMS packages are provided for computers running the following operating systems:

  • Microsoft Windowsâ 95
  • Windows NT Server
  • Windows NT Workstation
  • Windows version 3.1
  • Windows for Workgroups

For information about installing .pdf files, see your SMS documentation.


Changing the RPC Protocol Binding Order

When the Microsoft Exchange Client is installed, it sets the default RPC protocol binding order. This setting determines the protocol sequence that the Microsoft Exchange Client uses to communicate with Microsoft Exchange Server. You can change the RPC binding order before or after the client is installed.

Performance can be improved by changing the RPC binding order if the client uses multiple protocols or if the single protocol your client uses is not the first listed in the RPC binding order. If the protocol used is last in the sequence, the Microsoft Exchange Client attempts to bind over the protocols listed before it when connecting to the server.

The protocols are represented in the binding order, using the following entries. The string ncacn refers to Network Computing Architecture Connection.

Protocol name | RPC protocol string
Local RPC | ncalrpc
TCP/IP | ncacn_ip_tcp
SPX | ncacn_spx
Named pipes | ncacn_np
NetBIOS | netbios
VINES IP | ncacn_vns_spp

For example, the following entry attempts to establish connections over SPX, TCP/IP, and NetBIOS in that order.

RPC_Binding_Order=ncacn_spx,ncacn_ip_tcp,netbios

Clients Running Windows 95, Windows NT Server, and Windows NT Workstation

By default, Microsoft Exchange Client uses the following RPC binding order for Windows 95, Windows NT Server, and Windows NT Workstation when attempting to connect to a server.

1. TCP/IP

2. SPX

3. Named pipes

4. NetBIOS

5. VINES IP (Windows NT Server and Windows NT Workstation only)

You can change the RPC binding order for clients running Windows 95, Windows NT Workstation, and Windows NT Server before or after you've installed the Microsoft Exchange Client.

Before installation

In Setup Editor, select the Binding Order property page.

After installation

Use the Registry Editor to modify the binding order in HKEY_LOCAL_MACHINE\Microsoft\Exchange\Exchange Provider. For example, the following entry attempts to establish SPX, TCP/IP, and NetBIOS connections in the order indicated.

RPC_Binding_Order=ncacn_spx,ncacn_ip_tcp,netbios

Clients Running Windows and Windows for Workgroups

By default, the Microsoft Exchange Client uses the following RPC binding order for Windows for Workgroups when attempting to connect to a server.

1. Named pipes

2. SPX

3. TCP/IP

4. NetBIOS

5. VINES IP

You can change the RPC binding order for clients running Windows and Windows for Workgroups before or after you've installed Microsoft Exchange Client.

Before installation

In Setup Editor, select the Binding Order property page.

After installation

In the Exchng.ini file in the Windows directory, edit the [Exchange Provider] section. For example, the following entry in the Exchng.ini file attempts to establish SPX, TCP/IP, and NetBIOS connections in the order indicated.

[Exchange Provider]
RPC_Binding_Order=ncacn_spx,ncacn_ip_tcp,netbios

Clients Running MS-DOS

By default, the Microsoft Exchange Client uses the following RPC binding order for MS-DOS when attempting to connect to a server.

1. Local RPC

2. Named pipes

3. SPX

4. TCP/IP

5. NetBIOS

You can change the RPC binding order for clients running MS-DOS after you've installed MS-DOS. To change the order, edit the RPC_BINDING_ORDER line in the Mlsetup.ini file. This file is installed automatically on the client or on a network share. For example, the following entry in the Mlsetup.ini file attempts to establish local RPC, named pipes, TCP/IP, and NetBIOS connections in the order indicated.

RPC_Binding_Order=ncalrpc,ncacn_np,ncacn_ip_tcp,netbios


Uncompressing Installation Files for the Microsoft Exchange Client

Installation files for client Setup are stored on the Microsoft Exchange Client compact disc in multiple cabinet files. A cabinet (.cab) file includes many files that are stored as a single file. To view or access a file in a cabinet file, you can uncompress the cabinet file by using a command-line tool called Extract.exe. For example, if you want to use Newprof.exe, you can uncompress it from the Exchng3.cab file.

To uncompress a file in a cabinet file and place it in the current directory, type the following at the command prompt.

Extract cabinetfile /e filename

where cabinetfile is the name of the cabinet file and filename is the name of the file you want to uncompress.

For more information about using Extract.exe, type Extract /? at the command prompt.


Chapter 3 Working with MS Exchange Server

In working with Microsoft Exchange Server, you should perform server maintenance and understand how to back up and restore servers. You can customize the Microsoft Exchange Client for client languages and provide support for roving and remote users.


Maintaining Servers

The following tools can be used to maintain Microsoft Exchange Server:

  • Performance Monitor counters
  • Server and link monitors
  • Alerter service
  • Log files

For information about scheduling server maintenance, see Appendix B, "System Management Checklist."


Using Performance Monitor Counters

Use the Windows NT Performance Monitor to obtain information about the server status. You can keep the Performance Monitor running on each computer that is monitoring Microsoft Exchange Server. Microsoft Exchange Server includes several preconfigured Performance Monitor chart view (.pmw) files. These files are described in Appendix C, "Performance Monitor Chart Views."


Using Server and Link Monitors

The Administrator program includes server and link monitors.

  • Use server monitors to monitor the Microsoft Exchange Server services, such as the message transfer agent (MTA) or any other Windows NT services that are running on a Microsoft Exchange Server. You should configure server monitors to send a notification if the services go down and automatically restart the service.
  • Use link monitors to verify the connections between servers and foreign systems.

For more information, see the Microsoft Exchange Server Administrator's Guide.


Setting the Alerter Service

You can configure a Microsoft Exchange Server to notify a computer or user with system alerts (for example, when disk space is low).

To configure system alerts

1. In Control Panel, choose Server.

2. Choose the Alerts button.

3. Type the computer or user names to send alerts to in the New Computer or Username box.

4. Choose Add to add computers or user names, or choose Remove to remove them.


Maintaining Log Files

To keep log files from building up and consuming disk space, set up your server to maintain the log files or perform routine backups automatically. It is important to monitor the transaction log files and message tracking log files. The transaction log files track all information store and directory transactions. The message tracking log files track message deliveries and receipts.

Avoiding Build-Up of Transaction Log Files

You can avoid build-up of transaction log files by performing a backup or enabling circular logging. Use the backup method if you need to maintain an archive of the transaction log files. Use circular logging if you only need to access recent transaction information.

Caution

Do not manually delete the transaction log (edb*.log) files. To remove these files, do a full or incremental backup or turn circular logging on.

Performing a Backup

Perform a full or incremental online backup by using Windows NT Backup for Microsoft Exchange Server. When you do a backup, an archive of the transaction log file is created and the contents of the file are deleted. For more information about performing a backup, see the Microsoft Exchange Server Administrator's Guide.

Circular Logging

Circular logging reduces disk space requirements by overwriting transaction log files instead of storing them on the disk. Circular logging is enabled by default. With circular logging enabled:

  • You cannot do differential and incremental backups.
  • If you lose a database (*.edb) file, you can restore only up to the time a backup was made because you won't have the necessary log files to restore it up to the time the loss occurred.
To disable circular logging

1. In the Administrator window, choose a server.

2. From the File menu, choose Properties, and then select the Advanced tab.

3. In the Database circular logging box, clear Directory and Information store.

Automatically Deleting Message Tracking Log Files

You can configure your server to automatically delete message tracking log files. By default, message tracking log files are deleted after 7 days. If you disable this feature, you must periodically delete the message tracking log files manually.

To change when message tracking log files are automatically deleted

1. In the Administrator window, choose a site, the Configuration container, the Servers container, and then the server name.

2. Double-click System Attendant, and then select the General property page.

3. Select the Remove log files older than __ days box, and type the number of days the log files should be kept.


Backing Up and Restoring Servers

You should back up your Microsoft Exchange Server computers so that you can restore the servers with minimum downtime.

Use Windows NT Backup to back up the information store and directory. In addition, keep records of critical Windows NT settings such as the production server Internet Protocol (IP) address information and computer name. For information about backing up servers, see the Microsoft Exchange Server Administrator's Guide.

You need to back up and restore only the directory and information store because other components (such as the MTA and Microsoft Mail Connector) contain temporary data. For example, backing up the MTA would take an image of messages that are delivered seconds after the backup. Restoring this information would later result in duplicate messages. Some optional components, such as the Key Management (KM) server, have their own backup procedures. For more information, see the Microsoft Exchange Server Administrator's Guide.

Note

The values in the Windows NT Registry are also insignificant and should be reconfigured after reinstalling Microsoft Exchange Server.

Service information is stored in the Windows NT registry. Therefore, when you restore the information store and directory, the other Microsoft Exchange Server services are automatically restored to their default settings. For more information about restoring the information store and directory, see the Microsoft Exchange Server Administrator's Guide.


Restoring Data After a Catastrophe

If a server is catastrophically destroyed, the data must be restored from a backup. For procedures, see the Microsoft Exchange Server Administrator's Guide. In addition, note the following:

  • You cannot restore the directory to a computer with a different Windows NT domain, or you cannot access the information store. Ensure you add the restored machine to the original Windows NT domain.
  • If the Microsoft Exchange Server being restored is a primary domain controller (this may be the case in small remote sites), the security ID on the restored server must match the security ID from the original server. If the security ID on the restored server does not match the original security ID, you cannot access the information store unless you restore only the information store and manually rebuild the Windows NT accounts.


Restoring an Information Store to a Different Server

An information store can be restored to a Microsoft Exchange Server other than the one it was backed up from. Use this method as a last resort to recover individual items (messages or folders) from a backup without restoring on a server that is in use. This method requires an additional computer that meets the hardware requirements to run a Microsoft Exchange Server. The server should not be connected to the organization and should have enough disk space to restore the entire backup. For procedures to restore an information store, see the Microsoft Exchange Server Administrator's Guide. In addition, note the following:

  • Do not use this method when a server fails. This method restores only the information store; it does not restore the directory.
  • When you are finished restoring the backup, reconfigure permissions on the mailboxes.


Logging Download Information

The Microsoft Exchange Server download logging feature writes events to the Windows NT Event Log when users download attachments, messages, and folders from public or private folders. You can use this information for billing or tracking download costs.

A download event is logged when the user moves or copies an item from the private or public information store to a different store, such as a Personal Folder file. The item can be a message, attachment, or folder, depending on the configuration selected as described in the following section.

For example, if Log Downloads is set to 1 in the ParametersPublic registry key, every time a user moves or copies a message with an attachment to the user's Personal Folder file, an event is logged.

The following information is logged:

  • User name
  • Mailbox name
  • Size of item downloaded
  • Document type
  • Document identifier

The following example is an event generated by the download feature.

Ann Devon (ADEVON) downloaded 1456 bytes from attachment 6A

You establish download logging by editing the registry of a Microsoft Exchange Server with RegEdit, a Windows NT administrative tool. The values you add apply to all public and private folders on the server.

To start download logging

1. Start Regedt32.

2. Select the following registry key.

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIS

3. Select ParametersPublic to log downloads from public folders. Select ParametersPrivate to log downloads from private mailboxes.

4. From the Edit menu, choose Add Value.

5. In the Value box, type Log Downloads.

6. In the Data Type box, select REG_DWORD.

7. In the D_WORD Editor dialog box, type a decimal or binary value from the following table.

To log downloads from | Enter a registry value of |
 | Decimal | Binary
Attachments only | 1 | 001
Messages only | 2 | 010
Attachments and messages | 3 | 011
Folders only | 4 | 100
Attachments and folders | 5 | 101
Messages and folders | 6 | 110
All | 7 | 111

Use the Windows NT Event Viewer to review events recorded by the download logging feature.

To view logged downloads

1. In the Windows NT Administrative Tools program group, choose Event Viewer.

2. From the View menu, choose Filter Events.

3. In the Source box, select MSExchangeISPub or MSExchangeISPriv.

4. In the Category box, select Download.

5. Double-click an event to see its detail.


Customizing for Microsoft Exchange Client Languages

The code pages for Microsoft Exchange Client languages are installed with Microsoft Exchange Server. You can install language-specific indexes and details templates as well. Indexes provide users with sort and search orders common for the language. Details templates provide users with an Address Book in the language being used by the Microsoft Exchange Client.


Installing Indexes for Languages

An index for a language contains information on sorting and searching orders for folder hierarchies and the directory. The index is based on the language's conventions.

Installing a language index can minimize the confusion caused by differences in sorting and searching orders between languages; however, using multiple indexes can decrease server performance. To minimize the impact of multiple indexes, you can dedicate a single server for each index. You can also choose not to install languages that are needed infrequently or those that have similar sorting and searching rules as languages already installed on the server.

If an index for a Microsoft Exchange Client language is not installed on the Microsoft Exchange Server, the server uses an installed index that is similar to the language, or the Windows NT Server language.

To install a language index

1. In the Administrator window, choose Servers, and then choose the server you want to install the language index on.

2. From the File menu, choose Properties, and then select the Locales tab.

3. Select the language to be installed on the server.

4. Choose Add, and then choose OK.

5. Ensure the Windows NT code pages for the appropriate language are installed, and restart the server.


Installing Address Book Details Templates for Languages

You can customize the directory details template to change the language of the Address Book. The language details templates show text provided by the Microsoft Exchange Server (such as user properties in the Address Book) in the language on the Microsoft Exchange Client. Details templates for English, French, German, and Japanese are installed automatically. Installing language details templates does not affect server performance.

Note

Templates are not replicated across sites.

You can also customize the text shown in the display dialog box of the Address Book, such as what type of information is stored in the directory and the format the information is displayed in.

For more information about customizing details templates, see the Microsoft Exchange Server Administrator's Guide.


Booking Resources

You can use Microsoft Schedule+ to automatically schedule resources used in meetings, such as conference rooms and audio visual equipment. First set up a mailbox account for the resource, called a resource account, and then configure the resource account to accept meeting requests automatically. Users can then check the availability of resources through Schedule+ and automatically book resources by adding them to the Resource box in the Select Attendees dialog box.

To set up a resource account to book meeting requests automatically

1. Create an account and profile for the resource.

2. Log on to Schedule+ Version 7.0 as the resource account you created.

3. In the Welcome to Schedule+ 7.0 dialog box, select I Do Not Want a Schedule File on this Machine.

4. From the Tools menu, choose Options, and then select the General tab. Select the following options.

  • This Account is for a Resource
  • Automatically Accept Meeting Requests
  • Automatically Remove Canceled Meetings

5. From the Tools menu, choose Options. Select Synchronize and clear the Work Primarily from Local File box.

6. From the Tools menu, choose Set Access Permissions, and then select the Users tab. Set the following options.

  • Set the User Role in the Permissions Details for Default box to Create or higher.
  • Choose Add and select all users that should have access to the resource, and then choose OK.

7. Log off Schedule+.

To invite the resource to attend a meeting

Note

Automatically booking resources is enabled only when the resource account is entered in the Resource box of the Meeting Attendees dialog box. It is disabled if the resource is placed in the Required or Optional boxes.

1. Log on to Schedule+ as a user (not a resource account).

2. From the Insert menu, choose Appointments to display the New Appointment dialog box.

3. Select the General tab, and type a description of the appointment.

4. Select the Attendees tab, and then select required and optional attendees other than the resource.

5. Select the resource by typing the resource account name in the Resources box, or select the resource from the Address Book and select Resources.


Roving Users

Individuals who use the Microsoft Exchange Client on more than one computer are called roving users. The profile generator can be used to create profiles and set up roving users.


Using the Profile Generator

The profile generator simplifies the process of creating Microsoft Exchange Client profiles for roving users. When you create profiles for each type of operating system, users can use any computer with any operating system and still have access to their mailbox by double-clicking the Microsoft Exchange Client icon. Users do not need to re-create their profiles.

You can use the profile generator from the command line or with the Profgen.ini file. If you do not specify command-line options, the profile generator looks for a file called Profgen.ini and reads options from that file.

Windows Version 3.x and Windows for Workgroups

To support roving users who are using computers running Windows 3.x and Windows for Workgroups, Microsoft Exchange Clients should be running from a network share. During Setup, Messaging Application Programming Interface (MAPI) profiles are stored in the user's home directory or another location on a network file server.

You can assign logon scripts to users and make it easier for them to use the Microsoft Exchange Client on other computers in your organization. Logon scripts can connect users to their home directory when they log on to Windows and Windows for Workgroups. After a user is connected to the home directory and the Microsoft Exchange Client is started, the user's default profile is used.

When Microsoft Exchange Client is installed locally, it supports roving users. However, roving users must edit the Win.ini file.

To edit the Win.ini file

1. Open the Win.ini file using a text editor.

2. Add the following line to the [MAPI] section.

ProfileDirectory16=<path to messaging profile>

Where path to messaging profile is the location of the user's messaging profile on the network.

3. Restart the computer.

Û To use the profile generator with Windows 3.x or Windows for Workgroups computers

1. Copy Profgen.exe to C:\Exchange.

2. Copy Profgen.ini to C:\Windows.

3. In the Profgen.ini file, edit the PathToExeFile and PathToPRFFile to point to the automatic profile generator (Newprof.exe) and .prf files respectively. Normally these entries should be as follows.

PathToExeFile=c:\exchange\newprof.exe

PathToPRFFile=h:\Win16.prf

where h:\ is the user's home directory on the server.

4. Edit the Load= line in the Win.ini file as follows.

Load=c:\exchange\profgen.exe

5. In the Win.ini file, ensure the following line is present in the [MAPI] section.

ProfileDirectory16=home_directory:

where home_directory is the user's home directory on the server.

Windows NT Workstation and Windows 95

To support roving users who are using computers running Windows NT Workstation or Windows 95, you must store a user's MAPI profiles on the domain controller in a user's home domain. Storing the profiles in the user's home domain allows the users to access their profiles from any computer in your organization. If your roving users intend to use computers in other domains, you must permit the roving users to log on to multiple domains, and those domains must trust the user's home domain.

In addition, for Windows NT Workstation, ensure your roving users have user rights on the Windows NT Workstation computers they intend to use in your organization. If your roving users do not have user rights, they will be unable to log on.

To set up a roving user for Windows NT Workstation and Windows 95, you need to do the following:

  • Create a new user profile for the roving user.
  • Specify the path to the roving user's profile.
  • If the user is using computers from more than one domain, permit the roving user to log on to a different trusted domain.
To create a user profile for a Windows NT or Windows 95 roving user

Before creating the profile, log on to your domain's primary domain controller and the Windows NT Server computer as domain administrator. Ensure the Domain box displays the domain you want the account for the roving user to belong to.

1. In the Administrative Tools program group, choose User Profile Editor.

2. From the File menu, choose New.

3. Choose the button next to the Permitted to use profile box.

4. In the Names box, select the user account that should have permission to use this profile, or type the user name in the Add Name box and choose Add.

5. Choose OK.

6. From the File menu, choose Save As File.

7. In the Save File As Type box, choose Per-User Profile.

8. In the Directories box, choose the path for the profile.

You should store the profile in a shared user directory for security reasons. The profile can also be stored in a shared public directory.

9. In the File Name box, type a profile name, choose OK, and then close the User Profile Editor dialog box.

Before Windows NT roving users use Microsoft Exchange Server for the first time, you must verify their copy of Microsoft Exchange Server points to the network directory where the user profile is located. If it does not, change the working directory.

To change the working directory for the Microsoft Exchange Client on Windows NT

1. In the Microsoft Exchange program group of the Microsoft Exchange Client computer, choose Microsoft Exchange.

2. From the File menu, choose Properties.

3. In the Working Directory box, type the path of the directory where the roving user's profile is located.

Û To specify the path to a Windows NT or Windows 95 roving user's profile

1. In the Administrative Tools program group, choose User Manager for Domains.

2. Double-click the appropriate user account.

3. Choose Profile.

4. In the User Profile Path box, type the path to the profile (.usr) file you created earlier.

5. In the Home Directory box, select the Connect To option, and type the drive letter and path to the home server where the roving user's profile is located.

Before Windows 95 roving users use Microsoft Exchange Server for the first time, you must enable multiple users to customize preferences and desktop settings.

Note

Windows 95 profiles can be stored on any type of server, including a Novell NetWare server.

To permit a Windows NT or Windows 95 roving user to log on to a different domain

1. In the Administrative Tools program group, choose User Manager for Domains.

2. From the Policies menu, choose User Rights.

3. In the Right box, select Log on locally.

4. Select the Show Advanced User Rights box and choose Add.

5. In the List Names From box, select the domain you want to add the roving user account to.

6. In the Names box, select the user account for the roving user, choose Add, and then choose OK.

7. In the User Rights Policy dialog box, choose OK, and then close the User Manager for Domains dialog box.

To enable multiple users of a Microsoft Exchange Client computer to personalize their settings on Windows 95

1. In the Control Panel of the Microsoft Exchange Client computer, choose Passwords.

2. Select the User Profiles tab.

3. Select Users can customize their preferences and desktop settings.

To use the profile generator with Windows NT Workstation

Add the following line to the Windows NT Workstation domain logon script.

\\Server Name\Share Name\PROFGEN.EXE C:\EXCHANGE\NEWPROF.EXE -P H:\NTCLIENT.PRF

where H:\ is the user's home directory.

The automatic profile generator (Newprof.exe) must be located in the C:\Exchange directory. The profile generator (Profgen.exe) can be located on the local computer or the server.

To use the profile generator with Windows 95

1. Copy Profgen.exe to C:\Exchange.

2. Copy Profgen.ini to C:\Windows.

3. In the Profgen.ini file, edit the PathToExeFile and PathToPRFFile entries to point to automatic profile generator (Newprof.exe) and .prf files, respectively. Normally these entries should be as follows.

PathToExeFile=c:\exchange\newprof.exe
PathToPRFFile=h:\Win95.prf

where h:\ is the user's home directory on the server.

4. In the Win.ini file, edit the Load= line as follows.

Load=c:\exchange\profgen.exe

MS-DOS

To support a roving user on MS-DOS, you must store the profile in the user's home directory on a file server, and the Microsoft Exchange Client .exe file must be on a network share. When users run Workstation Setup from the network share, they must specify the home directory where they want to store their profile.

Assign logon scripts to users to make it easier for them to use the Microsoft Exchange Client on other computers in your organization. Logon scripts can automatically connect users to their home directory and the network share when they log on to MS-DOS. When a user is connected to the home directory and the Microsoft Exchange Client is started, the user's default profile is used.

To modify the logon scripts to connect users to their home directory

· Modify logon scripts to include the following lines.

set EXCHANGE=<home directory path>
set RPC_BINDING_ORDER=ncalrpc,ncacn_np,ncacn_spx,ncacn_ip_tcp,netbios

Note

If the user's logon script has been modified to set the home directory and the remote procedure call (RPC) binding order, the user should not modify the Autoexec.bat file during Setup. Otherwise, the information in the logon script and the Autoexec.bat file can conflict.


Using the Command Line

Using the profile generator from the command line allows you to customize the options each time you run it. Use the following syntax.

Profgen <path>\Newprof.exe -P <path>\Default.prf [-S] [-X] [-L] [-U]

The following table describes the command-line options.

Option | Description
<path>\Newprof.exe | Specifies the full path to Newprof.exe.
-P <path>\Default.prf | Specifies the full path to the .prf file.
-S | Runs Newprof.exe with the -S option.
-X | Runs Newprof.exe with the -X option.
-L | Creates a log file named C:\Profgen.log.
-U | Updates the MailboxName= entry in the .prf file specified with the -P option, even if it already contains a value. By default, if the entry contains a value, it is not updated.

Note

The -S and -X options are added to the command line for Newprof.exe only if they are specified on the Profgen.exe command line or in the Profgen.ini file.


Using the Profgen.ini File

The settings in the Profgen.ini file can be in the [NEWPROF] or [PROFGEN] sections. The following example is an entry in the [NEWPROF] section.

[NEWPROF]
; Provide the path to the NEWPROF.EXE executable
; e.g. c:\exchange\newprof.exe
PathToExeFile=c:\exchange\win95\newprof.exe

The following table describes the settings used in the Profgen.ini file.

[Section] and Setting | Description
[NEWPROF] |
PathToExeFile= | The path to the Newprof.exe executable file. For example, PathToExeFile=c:\exchange\win95\newprof.exe.
PathToPRFFile= | The path to the .prf file used to create the profile. For example, c:\exchange\default.prf. If this entry is blank, the program looks for the file Default.prf in the Windows directory. If a file is specified, but does not exist, the program quits and no profile is created.
DisplayUI= | Set to 1 if you want the profile generator user interface to be displayed. This setting is translated into the -S command-line option for Newprof.exe.
AutoExecute= | Set to 1 to run Newprof.exe with the -X command-line option.
[PROFGEN] |
Logging= | Set to 1 to create a log file called Profgen.log in C:.
UpdateMailboxName= | Set to 0 to replace the value of the MailboxName= entry in the .prf file with the current Windows NT logon ID. This only works if the MailboxName= entry in the .prf file contains a value.


Setting Up Users Accessing Microsoft Exchange Client from Multiple Windows Operating Systems

You can set up Microsoft Exchange Client users so they can move to any computer and access their mailbox, regardless of the Windows operating system.

Note

Roving users using the Microsoft Exchange Client for MS-DOS can access their mailboxes only from the MS-DOS client.

To set up a roving user for all operating systems

1. Set up each operating system to allow roving users. See the procedures later in this section.

2. Assign Windows NT domain logon scripts for each domain user.

3. Using the Windows NT Server User Manager for Domains program or a logon script, create a home directory for each user.

4. Copy three profile (.prf) files into each user's home directory, one for each platform. See the procedures later in this section. The profile is created the first time the user logs on to a computer with that operating system. The user should save the profile in the home directory and the profile will be available the next time the user logs on to any computer with the same operating system.

5. Follow the steps for each operating system that will be used. For more information, see "Using the Profile Generator" earlier in this chapter.

To set up the operating system to allow roving users

· Set up each operating system as follows.

Windows NT Use User Manager for Domains to create a user profile for each user.

Windows 95 Enable user profiles for Windows 95. In Control Panel, choose Passwords, and then choose User Profiles.

Windows 3.x and Windows for Workgroups Add the ProfileDirectory16=<home directory> line to the [MAPI] section of the Win.ini file.

To create profile files

1. Run the Microsoft Exchange Server Setup Editor at the client installation point for each operating system. Running the Setup Editor creates a Default.prf profile file in the client installation directory.

2. From the File menu, choose Set User Options, then select the Home Server tab. Ensure the Home Server box is completed.

3. Copy Default.prf to Win95.prf, Winnt.prf, and Win16.prf. These profile files can be identical and must contain all of the information to be added to the user profile, except the MailboxName. This is entered by the profile generator (Profgen.exe).

Windows NT Mandatory User Profiles

If you have mandatory user profiles, no changes to the Windows NT user profile are saved. Each time the user logs on, the default Windows NT profile overwrites the local Windows NT profile, so the Microsoft Exchange Client profiles created during one Windows NT logon session are not available the next time the user logs on.

Use the profile generator to automatically re-create the user's profile each time the user logs on to the Windows NT domain. The profile generator automatically renames the .prf file, so you use the Windows NT logon script to copy the .prf file.

To set up roving users with mandatory user profiles

1. Modify the Windows NT logon script to copy a .prf file into the user's home directory by adding the following line:

Copy \\<ServerName>\<Share>\Default.prf  H:\

where H:\ is the user's home directory.

2. Complete the steps in "Using the Profile Generator" earlier in this chapter.

Preventing Roving Users from Creating Local .Pst Files

For a roving user's mail to be accessible from each computer, the user must use only the server-based information store. If the user moves mail to a local .pst file (personal folders in the Microsoft Exchange Client), it will not be available from other computers.

You can prevent users from creating personal folders by installing the Microsoft Exchange Client without the personal folders service. Without this service, users cannot add personal folders to their profile.

To install the Microsoft Exchange Client without personal folders

Note

This works only if the Microsoft Exchange Client has never been installed on the computer.

1. Run the Microsoft Exchange Setup Editor at a client installation share point.

2. From the File menu, choose Select Client Installation Point.

3. Select the Services property page.

4. In the To be installed on the client box, select the Personal Folders service and choose Remove.

5. Choose OK and quit the program.

6. Run Microsoft Exchange Client Setup from the modified installation share point. The installed client will not have the personal folders service available.

If the Microsoft Exchange Client was previously installed on the computer with personal folders, personal folders are available even if you remove the client by selecting Remove All in Setup or if you reinstall with different services. The only way to remove the service is to edit the Mapisvf.inf file manually.

To remove personal folders from a Microsoft Exchange Client that has already been installed

1. Open the Mapisvf.inf file using a text editor.

2. Remove the following line from the [Services] section.

MSPST MS=Personal Folders


Remote Users

Microsoft Exchange Client remote users can establish network connections to personal and public folders on Microsoft Exchange Server computers by using a modem, a telephone line, and remote access software. Users who need to access the client remotely using a portable computer have several options for installing the Microsoft Exchange Client. They can install from:

  • A client installation point.
  • Microsoft Exchange Server compact disc.
  • Floppy disks.

For procedures to install the Microsoft Exchange Client from a client installation point or from the Microsoft Exchange Server compact disc, see the Microsoft Exchange Server Installation Guide.

To copy the Microsoft Exchange Client to floppy disks for remote users to install

1. Format several floppy disks. Label and number them sequentially.

2. From the Microsoft Exchange Client compact disc, go to the subdirectory for the client operating system where you are installing Microsoft Exchange Client.

3. Copy all files except the .cab files to Disk 1. Also copy Exchng1.cab to Disk 1.

4. Copy Exchng2.cab to the Disk 2, Exchng3.cab to the Disk 3, and so on, until you have copied all of the files to the disks.


Installing and Configuring ShivaRemote on a Microsoft Exchange Client

Microsoft Exchange Server includes ShivaRemote, a tool for accessing the server remotely for users running Windows version 3.x, Windows for Workgroups, and MS-DOS. For information about installing ShivaRemote for other operating systems, see the Config.hlp file located in the directory where ShivaRemote is installed.

Note

ShivaRemote does not support the Microsoft IPX/SPX protocol; however, it does support the Novell IPX protocol. For more information, see the Config.hlp file in the \Shiva subdirectory.

To install ShivaRemote for users on Windows 3.x and Windows for Workgroups

1. Copy ShivaRemote files to the Exchange\Shiva directory on a local disk.

2. In the Microsoft Exchange program group, choose ShivaRemote Setup.

To install ShivaRemote for users on MS-DOS

· During Microsoft Exchange Client Setup for MS-DOS, select the option to install ShivaRemote files to the Exchange\Shiva directory on a local disk.


Configuring a RAS Server for ShivaRemote Clients

A Microsoft Exchange Client user running ShivaRemote can connect directly to a server running Shiva LanRover or Windows NT Remote Access Service (RAS). If a Windows 3.x or Windows for Workgroups user is using ShivaRemote to connect to a Windows NT RAS server computer, the Microsoft Exchange Client must be configured as follows:

  • Users must have logon accounts with RAS enabled on the Windows NT Server computer.
  • The Windows NT Server computer must have RAS installed and configured to accept encrypted authentication.

To configure a Windows NT RAS Server computer to accept encrypted authentication for Microsoft Exchange Clients using ShivaRemote

1. Ensure RAS is installed on the Microsoft Exchange Server computer.

2. In Control Panel, choose Networks.

3. In the Installed Network Software box, select Remote Access Service and choose Configure.

4. In the Remote Access Setup dialog box, choose Network.

5. In the Network Configuration dialog box, select Require Encrypted Authentication, and choose OK.

6. Close all open dialog boxes.

7. Restart Windows NT Server.


Chapter 4 Public Folders

Public folders are storage areas on public information stores that allow you to group information so that it can be shared among multiple users. You can store many kinds of information in public folders, ranging from e-mail messages to graphics to sound bites. Public folders can also contain custom forms. These forms serve as a basis for creating custom applications such as bulletin boards, discussion forums, or customer tracking.

A public folder can also be used as an application, such as a bulletin board service, customer tracking application, electronic Help desk, or an Internet newsgroup discussion. By defining the type of information you want displayed and by organizing that information, you can create the application by using public folders exclusively.

Public folders are stored in the public information store (Exchsrvr\Mdbdata\Pub.edb) on a Microsoft Exchange Server computer. If you have more than one server, you can replicate public folders among servers so that users can access replicas of public folders on different servers.


Using Public Folders

Public folders provide a permanent storage place for information and allow the owners of the public folders to maintain the information.

You can also use public folders to track projects or customers. For example, suppose you have 25 customers that you work with on a regular basis. By setting up a public folder, you can track each customer by including notes from meetings with that customer, PowerPointâ presentations, a link to the customer's Web site, or a feedback survey.

Using public folders, you can update information quickly and easily. After a file or piece of information has been updated, you can immediately post it in a public folder where users can access it. You can also restrict the users who can access a public folder and generate automatic replies to contributors based on the characteristics of the information they post.

In addition, users can organize public folders in a way that is appropriate for their needs by using different views. By sorting on characteristics of their information, they can create layers of information that they can access directly. They can also add their most frequently used public folder to their list of public folder favorites.


Developing a Public Folder Strategy

To develop an effective public folder strategy, you first need to understand the public folder architecture. In addition, consider developing a public folder policy for your organization early in the planning process. Policy decisions determine the public folder hierarchy that everyone in the organization sees, who uses public folders, and for what purposes. These considerations influence where public folders are created and how much disk storage, CPU power, and memory you need to achieve adequate performance levels.

When you plan your public folder strategy, consider whether you want all your messages to be located in one public folder or in many public folders. This decision is important because it determines whether you need to replicate public folders to other servers.


Single Copy of a Public Folder

You can store the contents of a public folder on a single public folder server. This is the default configuration of a public folder when replication has not been configured.

The advantages of a single copy of a public folder are as follows:

  • Automatic load balancing for user requests
  • Availability in a wide area network (WAN). Users at sites with no direct connectivity can still share data.
  • Fault tolerance

The disadvantages of a single copy of a public folder are as follows:

  • Possible public folder conflicts
  • Latency issues
  • Additional message traffic associated with replication


Replicas of a Public Folder

Public folders can be replicated to other servers in your organization. That is, an identical replica of a public folder can appear on multiple servers. This is called a public folder replica. Replicas contain the same information as the originating public folder but reside on other Microsoft Exchange Server computers.

You can replicate a public folder to a server in the same site as the originating server or to servers in other sites. Replicating public folders to other servers in your site is useful for balancing the load of users who are accessing a public folder at any given time.

Replicating public folders to servers in remote sites is a good way to distribute the load to the remote site.

For more information on public folder replication, see "Public Folder Replication Strategies" later in this chapter.


Setting Up a Dedicated Public Folder Server

You can set up a dedicated public folder server to store and process requests for information about the public folder, such as its hierarchy and contents. A dedicated public folder server does not have a private information store.

Having a dedicated public server means that other servers can concentrate their processing efforts on private message storage and user message transfers. Dedicated public folder servers still participate in directory replication.

Consider using a dedicated public server when there is a large amount of data in a public folder system or when frequent and timely access to public folders is critical.

If you have a large site with more than 20 servers, you can benefit from not replicating the public folder hierarchy to every server, especially if public folders are created and deleted frequently. In this case, a private server may be your best option.


Dispersion of Workload

Each Microsoft Exchange Client obtains public folder hierarchy information from a public information store. If you have dedicated public servers, those servers respond to the clients for both hierarchical tree information and content data. As a result, it is possible for the servers to become overwhelmed with traffic. In this case, maintaining a public information store on each server enables clients to retrieve the hierarchical tree information from their local server while connecting to the public server for content data. In this way, requests for various types of data can be distributed for best performance.


Dedicated Public and Private Servers vs. Multipurpose Servers

As mentioned previously, you can centralize responsibilities among Microsoft Exchange Server computers by configuring all the Microsoft Exchange Server computers to be either public or private servers. A private server has a private information store (dedicated to private mail storage and user mail), but no public information store.

Configuring separate public and private servers allows you to plan the hardware needs for a particular computer according to its role. In other words, if you know that a public server will have heavy use, you can use a higher speed processor, more RAM, and so on.

Separating public and private servers also concentrates the flow of public folder traffic. In this way, replication of the public folder hierarchy and contents takes place only between the public servers and does not impact the private servers.

Specify Separate Responsibilities for Servers

You can assign different tasks to different servers.

To separate the responsibilities between public servers and private servers

1. Move all the public folders to the public servers by using the Replicas property page on the public folder or the Instances property page on the target public information store.

2. For each private server, configure the private information store so that the public folder server is the appropriate public server. To do this, use the General property page on the private information store server object.

This step ensures that all top-level public folders created in the future are located on the new public servers.

3. Use the Microsoft Exchange Server Administrator program to remove the private information store from the public servers and the public information store from the private servers. To do this, delete the private information store object from the server container in the Administrator program. Also, move mailboxes off of the public-only servers.


Setting Up Your Public Folders

When setting up public folders, you need to understand what types of folders you can create, where the hierarchy and content for the public folders are stored, and how public folders are located when a user accesses them. Reviewing these concepts before you set up your public folders helps you create a more efficient public folders system.


Creating a Public Folder

You create public folders by using the Microsoft Exchange Client. To install the Folder Design Cue Cards that you can use to create public folders, see the Microsoft Exchange Server Application Designer's Guide. However, you use the Administrator program to modify properties of existing folders.

To create a public folder

1. In the Client Viewer from the Tools menu, choose Application Design.

2. Choose Folder Design Cue Cards.


Top-level Folder and Subfolder Locations

When you create a top-level folder, it resides on the public folder server where you created it (for example, your hierarchy server).

When you create a subfolder, it inherits the replication configuration and replica list of its parent folder. This can later be changed by an administrator so that the parent folder and its subfolders are replicated to different servers.

The advantage of inheriting replication information is that the contents of the subfolders are available in the same locations with the same permissions as their parent folders.

If the top-level folder is not replicated, then all its subfolders are stored on the same public folder as the top-level folder. If the top-level folder is replicated, its subfolders are stored on every public folder server that contains a replica.


Creating Subfolders

You can create public folders that appear as subfolders. However, to do so, you must have been granted permission by the top-level folder owner, also known as the publishing author.

To create a subfolder

1. In the Microsoft Exchange Client Viewer, select the parent folder.

2. From the File menu, choose New Folder.

3. If you are writing a MAPI function call, use CreateFolder() on the parent folder object.


Public Folder Hierarchy

The public folder hierarchy is the tree structure that develops when you create multiple public folders by using top-level folders and subfolders. The hierarchy appears as a series of folders on the left side of the Microsoft Exchange Client Viewer.

Users can choose a public folder from the hierarchy as they would choose any other folder in the Viewer. The information store on their public folder server supplies the information on the hierarchy structure.

The public folder hierarchy is replicated to all public information stores within an organization.


Public Folder Contents

The contents of a public folder include a series of messages with attachments. The public folder contents exist on one or more Microsoft Exchange Servers with a public information store, also known as public folder servers. Although the hierarchy is stored on all public folder servers, the contents are stored only on some of the public folder servers.


Public Folder Locations

As previously mentioned, public folders are distributed, meaning that not all public folder contents reside in every information store. One advantage of this distribution is that the information in all public folders in an organization can be many times the size of the largest information store hard disk. One disadvantage is that additional automatic processing is needed to locate the information store where a particular public folder resides.

When you create a new public folder, an information store client creates a folder (Folder_Generic) in the public folder store hierarchy. Users who create folders are called folder owners and are identified through their personal information store.

After the public folder is created, the information store makes the folder accessible to other information stores. The folder owner can impose restrictions so that certain information store accounts (users) do not have access to the public folder.

All users have a hierarchy server they can connect to. This hierarchy server determines the hierarchy structure that should be displayed in their Microsoft Exchange Client Viewer. The hierarchy server is set on a per-private-server basis. A server with a private information store provides this setting in the General property page.


Public Folders in the Directory

Each folder that you create has an entry in the directory and appears as a recipient. Public folders are represented in the directory as the Public-Folder subclass of Mail-Recipient. Each public folder is represented in the directory by an item of the Public Folder object class, as shown in the following illustration.

By default, public folders are hidden recipients. To view these hidden folders, use the Microsoft Exchange Administrator program. From the View menu, choose Hidden Recipients.

Displaying Folder Addresses in the Address Book

To display a hidden folder in the recipient's list

1. In the Administrator window, double-click a public folder.

2. Select the Advanced tab.

3. Clear the Hide from Address Book check box.

Because public folders are represented as entries in the directory, you can send messages to them. In addition to mailing items to a public folder, you can post items in a public folder. Posting is a method of directly writing items to the information store without mailing them through the message transfer agent (MTA), as you do when you send a message.

Messaging Application Programming Interface (MAPI) clients with the appropriate permission can also post messages in a public folder synchronously by using the information store application programming interfaces (APIs).

Public folders appear in the Microsoft Exchange Address Book Provider top-level container with other classes of Microsoft Exchange recipients. The Display-Name attribute indicates the name of the folder as it appears in the container. The object class is used to indicate to the client (through MAPI) that the recipient is actually a public folder, not another recipient class.

You can create a special container for folder addresses. For example, if you want to group folders about a similar topic, you can create a container. To create a recipient container, select the public information store object and specify that this is where the recipient object is created.


Public Folder Store Structure

The public folder store is the primary mechanism used by MAPI clients to access public folders. The folder hierarchy represents all public folders and subfolders independent of the information stores in which they are located.

The public folder hierarchy is stored in the information store. The Microsoft Exchange Server service provider uses an index made up of the public folder objects to list the top-level folders to return to the MAPI client. When a MAPI application is used to view the subfolders of a top-level public folder, the provider connects to an information store that maintains an instance of the folder contents. The provider then accesses the information store for all subsequent contents operations in that folder.

All tree operations are performed by the user's hierarchy server. Content tables and messages are provided by the folder content servers.


Locating Folders by Using Affinities

When you select a public folder to view its contents, the information store must decide where that folder is located and which location it should connect to. The information store looks for the public folder in the following places in the order indicated.

1. The user's public folder hierarchy server.

2. A random number server in the site. If there are multiple replicas in the site, the store provider uses an algorithm based on the user's domain name to determine the next location to search. The resulting number is divided by the number of servers that contain that public folder in the site. A connection is then made to the server assigned to that number. Because the number is random, this method distributes connections across all the available replicas in the site.

3. An existing connection server in the site. If the information store cannot connect to the random number server, the remaining servers in the site are tried. Servers that already have remote procedure call (RPC) connections established are tried first.

4. Other sites. If public folder replicas are not available in the site but there is at least one other site available with replicas, the affinity number is used to determine the order in which connections are attempted.

The affinity number is set in the site's Public Folder Affinity property page. This setting allows an administrator to set a cost for each of the other sites in the organization. The cost determines the order in which the information store attempts to connect to those sites. The site with the lowest cost is attempted first.

After the site is determined, the servers within that site or group of sites are tried in random order. If two sites have the same cost, the servers in those sites are pooled together and tried in random order. Any sites without an affinity setting are not attempted.

In the following illustration, a user in Site 1 wants to connect to a public folder. Every server shown has a replica of the desired public folder. The numbers in the servers indicate the order in which the connections are attempted.


Customizing Public Folders

After you set up your public folders, you can use several features to help manage them. For example, you can designate who has access to a public folder, create a shortcut or favorite link to jump to a public folder quickly, or obtain information about a folder's properties.


Obtaining Information About a Folder

After you create a public folder, you can view information about its characteristics.

To obtain information about the type, location, and general description of a public folder

1. Select the folder.

2. From the File menu, choose Properties.

3. Select the General tab.

To obtain information about the folder contact, your permission level, and the folder path

1. Select the folder.

2. From the File menu, choose Properties.

3. Select the Summary tab.


Granting Access Control

You can control access to public folders by using the directory entries represented as mailboxes in the Address Book. Public folder owners can grant access permissions to any mailboxes represented by objects of the Distribution-List, Mailbox, and Public-Folder classes.

The following access permissions can be maintained for public folders:

Create items

You can create items in the folder.

Read items

You can read any items in the folder. Read Items permission is required for a user to open the folder's contents table.

Create subfolder

You can create subfolders in the folder.

Note that users with Create Subfolder permission have Owner permission for the subfolders they create. They can prevent any users from accessing those subfolders, including the owner(s) of the parent folder.

Edit items You have one of the following permissions:

Option | Description
None | You cannot edit items in the folder.
Own | You can edit only items that you created.
All | You can edit any item in the folder.

  • Delete items — You have one of the following permissions:
Option | Description
None | You cannot delete items in the folder.
Own | You can delete only items that you created.
All | You can delete any item in the folder.

  • Folder owner — You are the owner of the folder. Folder owners are granted all other permissions. Note that the name of the last owner is never removed from the folder's access control list.
  • Folder contact — You will receive replication conflict notifications, folder design conflict notifications, and quota notifications.

When you grant permissions to an Address Book entry of the DistributionList class, all the sublists of that distribution list are granted the same permissions. Distribution list members that are not represented by an X.500 Distinguished Name (that is, one-off addresses placed on distribution lists as X.400 originator/recipient addresses) are not granted permissions.

A public subfolder inherits the access control list of its parent unless the subfolder owner creates access controls specifically for the subfolder. If a folder has subfolders and you change the permissions for the parent folder, the permissions of the subfolders are not changed automatically. The changed permissions apply only to newly created subfolders.

Access cannot be granted on a per-message basis. That is, you cannot specify different levels of permissions for messages within the same public folder.


Deleting Public Folders

Only folder owners can delete public folders. Deleting a public folder prevents further access to the folder and its replicas and removes the representation of the folder and its subfolders from the directory.

Public folder deletions can be recursive, so if you attempt a nonrecursive deletion of a public folder that contains subfolders, you receive an error message.


Creating Shortcuts

To provide other users with quick and easy access to your public folders, create shortcuts to them. You can save a desktop shortcut file in any of your folders and then drag it into a message or another file to send to another user. For more information, see the Microsoft Exchange Client Help.


Creating a Favorites List

You can also create a list of public folders that you use frequently to jump to your favorite public folders without searching through the entire public folder tree. The list appears at the top of the public folder hierarchy in the Microsoft Exchange Client. Creating a list of favorites is particularly useful when a public folder hierarchy becomes large.

You can create a link to any favorite public folder or subfolder. Deleting a favorite removes it from the public folder favorite store, but does not remove the actual folder from the public information store.

For more information, see the Microsoft Exchange Client Help.


Public Folder Replication Strategies

The Microsoft Exchange Server allows you to distribute and synchronize shared information through public folder replication. In other words, you can take a public folder and replicate it to different Microsoft Exchange Server computers. These folders are called public folder replicas. A replica contains the same information as the originating public folder but resides on other Microsoft Exchange Server computers, as well as on the originating server.

As mentioned earlier, the process of keeping public folder replicas synchronized is called public folder replication. Public folder replication ensures that each copy of a public folder contains the same information as the corresponding replicas on other Microsoft Exchange Server computers. You can specify replication at regularly scheduled intervals.

To replicate public folders, a Microsoft Exchange Server computer sends messages to all other servers on the replica list and updates those replicas. The remote replicas are updated with new messages, attachments, and any other folder contents that have been added, deleted, or modified locally.

The only distinct member of the replica list is the Home-MDB. The server with the Home-MDB attribute in the public folder directory entry is the delivery location for items mailed to the folder.

For more information about setting a schedule for public folder replication, see the Microsoft Exchange Server Administrator's Guide.

Advantages of Public Folder Replication

Public folder replication results in the following benefits:

  • Distribution of processing load and improvement of response time for users accessing information in the folder.
  • Reduction in the amount of wide area network (WAN) traffic necessary to access information.
  • Increase in the availability of information for users when their primary server is unavailable.


Planning Considerations for Replication

There are several ways to reduce system traffic and increase system efficiency when you replicate public folders.

Maintaining Commonality in Replica Lists

One way to increase replication efficiency is to maintain commonality in replica lists when you create folders. This reduces traffic on the system because public folders are replicated more efficiently. Changes are aggregated for distribution to other servers based on commonality in the replica list.

For example, if you have a set of similar public folders that contain information on department budgets, make sure that all folders have the same replication list. If you perform the following steps in the order indicated, the subfolders inherit the replica list from the parent folder.

To maintain commonality in replica lists

1. Create a top-level folder.

2. Set the replica list as appropriate.

3. Create subfolders for the top-level folders.

Using Views Instead of New Folders for Similar Content

As the number of folders you have on your system increases, so do the time and resources needed to replicate the folder hierarchy. To avoid this, create a single folder with different views to display information.

For example, instead of creating a folder for each employee in your department, you can create a single folder and designate the name of each employee as a field in that folder. That way, you can sort on an employee's name when you want to see information about that employee.

Dedicating Servers for Specific Purposes

By creating servers that each deal with a specific application, task, or function, you can increase system efficiency. For example, use one server to handle only the bulletin board system (BBS) tree and another folder to handle only Microsoft Schedule+ data. When you do so, be careful not to overcentralize. This causes every user of a particular application to access the same server. Instead, widely used data, such as Schedule + free/busy information, needs to be distributed to multiple servers.


Configuring Public Folder Hierarchy Replication

Each public folder server contains a replica of the hierarchy of all the public folders in the organization. This information is read by Microsoft Exchange Client computers and appears as a series of folders on the left side of the Microsoft Exchange Client Viewer.

You cannot configure hierarchy replication as you would content replication. Hierarchy replication takes place automatically at an interval set in the registry. When a user logs on to a client, the client automatically reads the hierarchy from its public folder server.

When you create a top-level public folder, the folder, its hierarchy, and the contents are added to the Pub.edb file on your public folder server. The information is then sent as mail messages delivered by the MTA. After replication, users in the organization who are viewing information in the Pub.edb file for their public folder server see the new public folder in the hierarchy.

As shown in the following illustration, any hierarchy changes are replicated to all servers in the organization.

From then on, when a user searches for information on the new public folder, the public information store on the local public folder server automatically directs the client computer to a public folder server that has the contents.

For more information on configuring hierarchy replication, see the Microsoft Exchange Server Administrator's Guide.


Configuring Public Folder Content Replication

You can replicate public folders to different servers in the same site or to servers in other sites. As previously mentioned, replicating public folders to other servers is an effective way to balance the load of users accessing a particular public folder at a given time. For example, if you have 100 users and 3 public folder servers in a site, and all 100 users access a particular folder many times a day, this can create an excessive amount of traffic on that server. However, if you create a public folder replica on a second server, the information stores on both servers can balance the load of users.

The following illustration shows how public folder contents can be replicated to different sites.

The information store supports a multimaster replication model for public folders. That is, you can make changes directly to any replica of a public folder or to messages within the folder and these changes will be replicated to all other replicas. For example, when you modify a message or an attachment in a message in a public folder, the message and its attachments are replicated to all the other public folder instances. Changes are replicated with document-level granularity, which means that if a single document is changed in a folder with hundreds of documents, only the document that is changed is replicated.

Public folder replication is e-mail based. This allows replicated instances of public folders to reside on information stores located on different physical local area networks (LANs) where only e-mail may be connecting them.

The store-and-forward nature of message routing allows for replication message fan-out. This minimizes network overhead when the number of replicas is high because of delayed splitting of recipient messages.


Replicating Messages

When more than one instance of a public folder has been configured, the public folder replication agent (PFRA) — a component of the information store — monitors changes, additions, and deletions to the original public folder and other replicated public folders. These public folders are configured to have replicas on the information store. They are also configured for sending change messages to other information stores on which replicated instances have been configured.

The replicated messages are transported as embedded messages in message database encoding format (MDBEF), which is the file format used by the Microsoft Exchange Server information store. Each replicated message includes a change number that identifies it in relationship to existing replication messages.

Tracking of Modified Messages

The PFRA maintains the following information about the state of each message in each folder.

  • A monotomically increasing, information store-specific change number.
  • A list of predecessor change numbers (all previous change numbers for an information store)

The change number is made up of a unique identifier and a change counter, so the change numbers are information store-specific.

The change counter is assigned a number by the PFRA for each message change that occurs on a server. When a message on an information store is modified, the PFRA for that information store assigns a new change number to the message so that the change counter is greater than the previous one.

By using the predecessor change number list, the PRFA tracks which version of a message is the most current.

Replication of Modified Messages

When you edit a message in a replicated public folder, the PFRA for that information store updates the state information for that message. It then sends a replication message containing the modified message and its attachments to the other information stores that maintain replicas. The list of information stores that maintain these replicas is a property of the folder.

When an information store receives a new replication message, the new message replaces the existing message on the local computer if the original message modification was made to the same version or a later version of the existing message. In other words, if the new message is more current than the existing message, then the new message replaces the existing message.

The message that contains the most recent information is determined by the change number and the predecessor change list. If the change number of the existing message is included in the predecessor change list of the new message, the new message replaces the existing message.

The following illustration shows how replication occurs when there are no conflicts.

Replication Conflicts

Conflicts occur when a message is modified in two different replicas, where each modification is made before the other can replicate. For example, if the change number of the current message is not included in the predecessor list of the new message, the new message is older than the existing message. In this case, a change was made to a message that had not incorporated a previous change from another information store. As shown in the following illustration, a conflict has occurred.

When a conflict occurs, the information store alerts the folder contacts of the conflict by attaching the conflicting messages to a conflict notification. This is shown in the following illustration.

The folder contact can resolve the conflict at any of the instances. As shown in the following illustration, the resolved message replicates to the other folder instances.

Replication of New and Deleted Messages

When a new message is created in a public folder, the information store assigns a change counter number to the message and sends a replication message to all other information stores maintaining instances of the public folder. Information stores receiving the replication message create the message in their replica of the public folder, using the change number assigned by the information store the message was created on.

When a message is deleted, the information store from which the message is deleted sends a replication message to all other information stores maintaining instances of the public folder. This message indicates that the message has been deleted. Each receiving information store then deletes its instance of the message and maintains a tombstone for the deleted message.

Replication Frequency

Because public folder replication is e-mail-based, the time for messages to replicate from one information store to a particular replica depends on the underlying messaging system and topology, as well as administrator-specified MTA connection parameters.

Scheduling for replication is configured in the Administrator program on a per-folder and per-information store basis. A Replication Schedule property page on the public folder object permits replication scheduling in 15-minute intervals. The same property page exists on the public information store object. If a schedule is set on the folder level, it overrides the schedule set at the information store level.


Backfilling

Although the Microsoft Exchange Server MTA guarantees a high degree of reliability (particularly in a homogenous environment), it cannot guarantee that replication messages or confirmation notifications will not be lost due to hardware failure or other problems. This is particularly true where public folder replicas are configured to reside in different sites and a foreign system is used for MTA connectivity between the sites. For this reason, information stores must be able to cope with lost replication messages. It does so through backfilling.

Backfilling is the process of acquiring information that was lost from an information store due to one of the following circumstances:

  • A new replica was added to a server and does not have any information replicated to it.
  • A message was lost in transit.
  • A server was restored from backup.

A server needs to be backfilled when it has not successfully received all the replica messages from other information stores.

When an information store fails to receive complete replica information, it generates a backfill entry, which serves as a placeholder to indicate that information is missing. After waiting for a specified amount of time to receive the missing folder content packet, the information store issues a backfill request to two other servers chosen by a predetermined algorithm. The backfill request indicates which folder content packet is missing and requests that another information store send the information. Any information store can respond to a backfill request, regardless of whether it was the source of the original folder content packet.

Adding a Replica

To create a replica of an existing public folder, you must have public folder administrator authority. Start the Administrator program and then add the new information store to the Instances property page of the public folder, or add the public folder to the Replicas property page of the public information store.

When an information store detects a new replica and determines that it is responsible for that replica, it generates a backfill request for the contents of the folder (the folder content packet).

If an information store receives a folder content packet for a folder that does not exist in the hierarchy or for which it does not currently have a replica, it queues the content packet and waits for the folder hierarchy change. It then processes the content packet. If the hierarchy change does not occur within four hours, the packet expires and will have to be backfilled.

Replication Verification Tool

The Public Folder Replication Verification Tool (Replver.exe) compares public folders on Microsoft Exchange Server computers and sends periodic status messages if a replica appears to be out-of-date.

For more information, see the Microsoft Exchange Server version 4.0 compact disc Readme file.


Deleting a Directory Replication Connector

Before you delete a directory replication connection between one or more Microsoft Exchange Server sites, consider whether or not to run the DS/IS consistency adjuster, which compares the directory with the information store.

Warning

If you delete a directory replication connector between two sites and you plan to reconnect the two sites later, do not run the DS/IS consistency adjuster. This could result in a loss of data.

When you disconnect a directory replication connector and then run the DS/IS consistency adjuster tool, you not only prevent replication between the two sites, you also reestablish the home folder between the public folder replicas. Although all public folders that were available before you removed the connector will still be available, they cease to be exact replicas of each other. For example, if a user makes a change to a message in a public folder in Site 1 and another user changes the same message in Site 2, their changes do not appear outside the respective sites.

In addition, when the directory replication connector is removed, Microsoft Exchange Server reestablishes the home folder based on the folder where the most recent change was made. For example, if there is a public folder in Site 2 and a user edits a message in that public folder before the sites are disconnected, then the public folder in Site 2 becomes the home folder. So if the two sites are disconnected and you delete a public folder in Site 1, reconnecting causes the information store to backfill the deleted public folder to the home server (Site 2). The backfill deletes the public folder in Site 2, even if additional changes were made to it when the sites were disconnected.


Using Forms Designer with Public Folders

You can use custom forms to create surveys, classified ads, or order forms that you want to manage by working with public folders. Use the Microsoft Exchange Forms Designer to create forms and applications, and then work in Microsoft Visual C++â to extend the functionality of these forms and applications. The Forms Designer even contains sample applications that you can adopt as-is or modify to suit your purposes.

For more information, see the Microsoft Exchange Server Application Designer's Guide. You can also visit the Application Farm Web site at:

http://www.microsoft.com/technet/boes/bo/mailexch/exch/tools/appfarm/appfarm1.htm

Considering All Storage Options

When you store forms, there are two locations to choose from:

  • Public folders
  • Organization forms library

Public folders allow many users to view and store information and are useful when you have many people adding information or posting forms.

The organization forms library is more restrictive than public folders because only an administrator can install the forms. However, this can be changed by allowing all users to have full ownership permissions for the organization forms library.


Chapter 5 X.400 Connector

You can use the X.400 Connector to establish an X.400 messaging route between two Microsoft Exchange Server sites or between a Microsoft Exchange Server site and a foreign X.400 system. An X.400 messaging route defines the path that an X.400 message follows to reach its destination. It allows the message transfer agents (MTAs) in both sites or systems to communicate. A foreign X.400 system is a messaging system other than Microsoft Exchange Server that complies with the 1984 or 1988 X.400 standards.


Understanding X.400

The X.400 recommendation defines the standards of an electronic messaging system and enables users to exchange messages regardless of the system.

The X.400 Recommendations were developed by an organization known as the Comité Consultatif International Télégraphique et Téléphonic (CCITT). The CCITT publishes recommendations every four years. Each publication is identified by a color:

  • 1984 - Red Book
  • 1988 - Blue Book
  • 1992 - White Book

The Electronic Messaging Association (EMA), develops specifications for e-mail software development. It is comprised of private e-mail software-development companies. The EMA publishes standards that further define the X.400 Recommendations.

The X.400 Recommendations are based on the Open Systems Interconnection (OSI) reference model defined by the International Organization for Standardization (ISO). The X.400 Recommendations specify the structure of a message handling system, message structure and components, and the method used to transfer messages. Microsoft Exchange Server complies with the 1984 and 1988 X.400 Recommendations.

The OSI reference model provides a layered architecture that standardizes the method computers use to exchange information through a communications network. The OSI model separates computer-to-computer communications into seven layers: application, presentation, session, transport, network, data link, and physical. The top three layers usually relate to the operating system and applications that run on it. The other layers determine the way networks interconnect.

Using the OSI model, an administrator can choose the physical network, the protocols and transports transmitted over the network, and the software and hardware used on each end of the connection. As long as each layer receives and transmits information correctly to the layers above and below, it doesn't matter what combination of hardware and software is used in each layer.

X.400 runs on the application layer of the OSI model. This allows application processes to access network services. X.400 represents services that support user applications, such as software for file transfers, database access, and e-mail. The following diagram illustrates the seven OSI layers and examples of some of the protocols and standards that are used in each layer.


X.400 Message Handling System

An X.400 message handling system (MHS) is a collection of components that work together to transfer messages. The X.400 Recommendations specify that an MHS should have the following components.

Component | Description
User agent (UA) | Prepares, submits, and receives messages for a user. Displays messages and provides other functions such as text editing and security.
Message transfer agent (MTA) | Forwards and relays messages within the network.
Message transfer system (MTS) | Two or more MTAs.
Message store (MS) | Stores messages transferred between MTAs and user agents. (1988 Recommendations only.) Known as the information store in Microsoft Exchange Server.
Access unit (AU) | Gateway to other messaging systems.

The set of message handling system components and users is called a message handling environment (MHE). An MHE can include several messaging systems connected through gateways or public data networks or just one message handling system where messages are contained within the system.

An X.400 MHS usually works with directory services, including the directory user agent and directory system agent. Directory services are not part of the X.400 Recommendations, but the 1988 X.400 Recommendations allow the use of directory services. The directory is a database of all objects in the message handling system, such as mailboxes and distribution lists. The following diagram illustrates how the components of the MHS work together to transfer messages.

The user agents and message transfer agents in the MHS form the message transfer system (MTS) and the interpersonal messaging service (IPMS).

The MTS is a collection of one or more MTAs that submit, transfer, and deliver messages through the MHS. The MTS is the infrastructure of message handling.

In the following example, a user agent submits a message to the MTA within the MTS for delivery to one or more MTS users. The MTS accepts the message and provides any necessary store and forward features, such as distributing the message to more than one recipient. The MTA then routes and delivers the message.

The IPMS allows messages to be exchanged from person to person. When a message is sent from one user to another, the IPMS invokes the services of the underlying MTS to submit and deliver the message to its destination. The following illustration shows how the MTS functions within the IPMS.

There are two types of IPMS messages: interpersonal messages and interpersonal message notifications. The interpersonal message contains text, graphics, or other content sent from one user to another. The interpersonal message notification contains information about the status of the delivery of the message, or whether the message was read or not read.

Transferring Messages Through the MHS

Messages are transferred through the MHS by protocols defined in the X.400 Recommendations. The protocol for each message component is assigned a number. The following are the most common protocols.

Component | Protocol
Envelope | P1
Message content (1984) | P2
Client-MTA communications | P3
Client-message store (MS) | P7
Message content (1988) | P22

Message Components

An X.400 message has two components: an envelope and its content.

The envelope contains addressing information, including the address of the originator and recipient, the delivery priority, and message trace information. The envelope is formatted by using the P1 protocol.

Most X.400 messages are made up of one or more body parts, together with header information. The body parts make up the text of the message. The header contains address, routing, and trace information, and determines how the message is transported.

The X.400 body contains the actual message, which can contain text, graphics, voice, or other kinds of data. The X.400 Recommendations specify standards for different types of content found in body parts. Body parts are referred to by body part numbers. The following table shows the X.400 body part types and numbers that can be used with the Microsoft Exchange Server.

Body Part Type | Body Part Number | Description
IA5 text | BP 0 | International alphabet number 5. Includes U.S. English, German, Norwegian, and Swedish.
Teletex 61 | BP 5 | U.S. English teletex.
Forwarded interpersonal message | BP 9 | Embedded and forwarded messages.
ISO 6937 text | BP 13 | Eastern Europe and German characters.
Bilaterally-defined (binary) | BP 14 | Simple transfer of binary attachments.
Binary file transfer (FTBP) | BP 15 FTBP | Transfer of attachments using FTBP, which includes file name, size, and properties. Available for MTA conformance modes only.
ISO 8859-1 | Encapsulated within BP 15 | Latin 1 code page. Available for MTA conformance modes only.

The header fields contain information such as the message originator, recipients, and expiration time, which is useful for tracing messages and troubleshooting. Microsoft Exchange Server uses the following header fields.

Field | Description
originator | O/R address of originator.
authorizing-users | O/R addresses of send on behalf of.
primary-recipients | Recipients specified on the To line.
copy-recipients | Recipients specified on Cc line.
blind-copy-recipients | Recipients specified on Bcc line.
expiry-time | Message is deleted if it is not read by the specified time.
deferred-delivery-time | Message is sent at the specified time.
subject | Up to 128 characters. Sent using Teletex T.61.
importance | Low, medium, or high.
sensitivity | Low, medium, or high.


Microsoft Exchange Server Content Options

It is important to understand how Microsoft Exchange Server implements X.400 content options to ensure messages are transferred correctly. The options you use depend upon the X.400 system you connect to.

You specify content options in the X.400 Connector Advanced property page using the Microsoft Exchange Server Administrator program. When you configure for 1984 MTA conformance, text content is sent using the P2 protocol, and attachments are sent using BP 14. When you configure for 1988 MTA conformance, text content is sent using the P22 protocol, and you can configure the server to send attachments using either BP 14 and BP 15 (FTBP).

In addition to the P2 and P22 content types, Microsoft Exchange Server provides a third message content type called message database encoding format (MDBEF). MDBEF is the format used by the Microsoft Exchange Server information store. Using MDBEF with an X.400 Connector between two Microsoft Exchange Server sites provides faster throughput because messages do not have to be converted to P2/22 and then back to MDBEF. To send messages using MDBEF content, select the Allow Microsoft Exchange contents box under X.400 link options of the X.400 Advanced property page. The Microsoft Exchange Servers must be replicated to transmit messages in MDBEF format.

Messages containing Messaging Application Programming Interface (MAPI) properties, such as rich text formatting and object linking and embedding (OLE) attachments, are encapsulated using the transport-neutral encapsulation format (TNEF), and sent as an X.400 attachment. If the receiving system can process the TNEF attachment, the message is displayed with the rich text formatting or icon representation. If the receiving system cannot process TNEF or MAPI attachments, the message text and attachments may not be readable.

The Microsoft Exchange Server MTA is capable of relaying messages from a 1988 X.400 link to a 1984 X.400 link and vice versa. However, when the Microsoft Exchange Server MTA relays a 1988 body part that is not supported by a 1984 X.400 system, the message content appears blank on the receiving system.

For example, ISO 8859-1 is a 1988 body part that is not supported on a 1984 link. The Microsoft Exchange Server relay MTA is connected to a system on the 1988 link that supports ISO 8859-1 and to a system on the 1984 link that supports IA5. The Microsoft Exchange Server relay MTA cannot convert ISO 8859-1 to a supported 1984 body part such as IA5. You can use the Convert incoming messages to MS Exchange contents option on the relay MTA's General property page to convert the content to MDBEF. The content can then be converted to the P2 format of the receiving system connected by the 1984 link.


X.400 Addressing

A management domain (MD) is a set of messaging systems managed by an organization that contains at least one message transfer agent. The management domain is divided into two parts: administrative management domain (ADMD) and private management domain (PRMD).

An ADMD is managed by a public service provider and is the highest level management domain that transmits third-party message traffic. The service is usually provided by a telephone carrier such as Sprint, AT&T, or British Telecom.

A PRMD is a network owned by a private company. PRMDs can communicate with ADMDs and other PRMDs but are not permitted to relay messages between PRMDs.

The ADMD and PRMD structure is similar to the telephone system. An ADMD can be compared to a telephone carrier that you receive phone service from. The service is leased from the ADMD in the form of a PRMD. This is similar to how a telephone line is assigned. The PRMD has a unique network address that can have multiple users.


Originator/Recipient (O/R) Addresses

Users of a message transfer system are identified by an Originator/Recipient (O/R) name. The O/R name is included on the P1 envelope and is used by the MTS to route and deliver messages.

Microsoft Exchange Server automatically creates X.400 addresses for every mailbox based on the site and organization name you specify during Setup. It is important to understand the elements of O/R addresses to modify the site address, create custom recipient addresses, and specify the addresses of other X.400 systems in the X.400 Connector configuration.

The O/R address is comprised of required and optional fields containing attributes and values. The attributes necessary for a valid address vary depending on the recipient system. All attributes are not required for delivery in an X.400 system. Once the correct attributes are identified, the attribute and its value are combined in an address format with an equal sign (=) separating the two. A delimiter is added between fields for parsing reasons. X.400 fields can be separated by a semicolon (;) or a slash (/). Different systems can require different delimiters.

You can use either the abbreviation or the label to identify an attribute. The following table shows valid abbreviations and labels, as well as the maximum length allowed for the value. The DDA field is case sensitive; the other attributes are not.

Attribute Type | Abbreviation | Label | Maximum Characters
Given name | Given name | G | 16
Initials | Initials | I | 5
Surname | Surname | S | 40
Generation qualifier | Generation | Q | 3
Common name | Common name | CN | 32
X.121 address | X.121 | X.121 | 15
User agent numeric ID | N-ID | N-ID | 32
Terminal type | T-TY | T-TY | 3
Terminal identifier | T-ID | T-ID | 24
Organization | Organization | O | 64
Organizational unit 1 | Org.Unit.1 | OU1 | 32
Organizational unit 2 | Org.Unit.2 | OU2 | 32
Organizational unit 3 | Org.Unit.3 | OU3 | 32
Organizational unit 4 | Org.Unit.4 | OU4 | 32
Private management domain name | PRMD | P | 16
Administrative management domain name | ADMD | A | 16
Country | Country | C | 2
Domain defined attribute | DDA | DDA | 8, 128

DDA uses the format DDA:type=value; for example, DDA:SMTP=MariaBlack@fab.com. There may be up to four DDAs in a single X.400 address. DDAs are order dependent. When parsing from left to right, the first DDA is encoded first, the second DDA is encoded second, and so on.

With the exception of DDA, the format for the fields is Label=Value; for example, g=Joe. The following are examples of valid X.400 addresses using labels and different delimiters:

  • C=US;A=MCI;P=MSFT;S=EMAIL
  • C=US;ADMD=MCI;PRMD=FAB;S=EMAIL
  • C=US/ADMD=MCI/PRMD=FAB/S=EMAIL
  • C=US;A=TELEMAIL;P=MMC;O=SALES;OU1=INSIDE;S=LAST;G=FIRST
  • C=US;ADMD=TELEMAIL;PRMD=MMC;O=SALES;OU1=INSIDE;S=LAST;G=FIRST
  • C=US/A=TELEMAIL/P=MMC/O=SALES/OU1=INSIDE/S=LAST/G=FIRST
  • C=US/ADMD=TELEMAIL/PRMD=MMC/O=SALES/OU1=INSIDE/S=LAST/G=FIRST


X.400 Addresses in Microsoft Exchange Server

An X.400 address is composed by providing the value for all required attributes and any optional attributes until a unique address is created. The following table illustrates the required and optional attributes that can be used to create a mnemonic X.400 address with Microsoft Exchange Server. All attribute values can contain numeric or alphanumeric characters.

Attribute | Comments
Personal name | Includes Given Name, Initials, Surname, and Generation. If the Personal Name attributes are used, the Surname is required.
Common name | Optional
Organization | Optional
Organizational units | Optional
PRMD | Optional
ADMD | Required. A single blank character can be used in the ADMD field to indicate that no ADMD is specified.
Country | Required
DDAs | Optional

Note

At least one of the Personal Name, Common Name, Organization, Organizational Units, or PRMD attributes must be used in addition to ADMD and Country. If a DDA is used, you still must specify one of the other optional fields.

Microsoft Exchange Server can use X.121 addresses in the X.400 environment. X.121 is a standard universal addressing scheme for public data networks. The following table illustrates the required and optional attributes that can be used to create an X.121 address with Microsoft Exchange Server. All attribute values can contain numeric or alphanumeric characters.

Attribute | Comments
X.121 address | Required
PRMD | Required only for 1988 X.400 compatibility.
ADMD | Required. A single blank character can be used in the ADMD field to indicate that no ADMD is specified.
Country | Required
DDAs | Optional

For more information about X.400 address attributes, see Microsoft Exchange Server Administrator's Guide.

Global Domain Identifier

Microsoft Exchange Server uses the X.400 global domain identifier (GDI) in a relay environment. The GDI is comprised of the country, ADMD, and PRMD name of the remote MTA. It is used for inserting trace elements and can be used for troubleshooting an unsuccessful relay attempt. It is also used to prevent message looping in wide-area messaging environments.

If you are using a public X.400 network as a backbone between two Microsoft Exchange Servers, messages may not be routed correctly if the GDI used for Microsoft Exchange Server is the same as the GDI of a connected foreign system.


Chapter 6 Addressing and Routing

Understanding addressing and how e-mail messages are routed through the Microsoft Exchange Server can help you optimize Microsoft Exchange Server performance and reliability. It can also be useful for troubleshooting message routing problems.


Addresses

Microsoft Exchange Server uses a variety of addresses. Each Microsoft Exchange Server has a site address, and each mailbox has a recipient address. Custom addresses can be created for recipients on other mail systems. Address spaces are used by connectors to define the types of messages they transmit.


Site and Recipient Addresses

Microsoft Exchange Server creates site addresses by using the organization name and site name provided during Setup. Recipient addresses are created by using site addresses. Site and recipient addresses are stored in the directory. It is important to ensure you have valid site addresses before adding mailboxes or connectors.

Site and recipient addresses are created for the following address types: MS (MS Mail for PC Networks), SMTP (Internet), and X400 (X.400). If third-party gateways are installed, other addresses can also be generated.

Microsoft Exchange Server creates a distinguished name (DN) for every object in the directory, such as a mailbox or distribution list. The DN is used to route messages within a Microsoft Exchange Server organization. If the DN cannot be resolved, the Microsoft Exchange Server uses the X.400 address of the object. It is important to retain the X.400 address for every object in the directory, even if you are not connecting to another X.400 system.

A recipient on a foreign system who has an address stored in the Microsoft Exchange Server directory is called a custom recipient.

When a message is routed to a custom recipient, the DN of the recipient and originator are replaced with an address of the same type as the recipient. This ensures the message can be delivered to the foreign system, and a reply can be routed back to the originator with the correct address type. An illustration of the address conversion follows.

If the recipient is not defined in the Microsoft Exchange Server directory, the address must be in the form required by the foreign system. In this case, only the originator's address is converted to the native format of the foreign system.

For more information about site and recipient addresses, see the Microsoft Exchange Server Concepts and Planning Guide. For information about how to view and modify site and recipient addresses, see the Microsoft Exchange Server Administrator's Guide.


Address Spaces

Microsoft Exchange Server connectors are gateways used to create paths for messages sent outside a site. The following connectors are available with the Microsoft Exchange Server.

Connector | Connects to
Site Connector | Another Microsoft Exchange Server.
Dynamic RAS Connector | Another Microsoft Exchange Server.
X.400 Connector | Another Microsoft Exchange Server or an X.400 system.
Microsoft Mail Connector | Servers running MS Mail.
Internet Mail Connector | Another Microsoft Exchange Server or another system using simple mail transfer protocol (SMTP).

The path a connector uses to send messages outside the site is represented by an address space. The address space identifies the recipient address types and addresses. A connector must have at least one address space.

As shown in the following illustration, Ferguson and Bardell are using the Internet Mail Connector to establish a link to the company's West coast Internet provider. The Internet Mail Connector address space is type SMTP and the address is *.com. The message transfer agent (MTA) uses this Internet Mail Connector to process only SMTP messages addressed to recipients with the .com domain identifier.

For more information about address spaces, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server Administrator's Guide.


Routing

Understanding how routing works can help you configure the Microsoft Exchange Server for efficient message transfer. Messages are submitted to the Microsoft Exchange Server by a user, another Microsoft Exchange Server, or a foreign mail system through a connector or gateway.

Messages can be routed to the following:

  • A recipient on the same server.
  • A recipient on a different server in the same site.
  • A recipient in a different site or foreign system.


Routing on the Same Server

When the recipient is on the same server as the originator, the Microsoft Exchange Server information store delivers the message directly to the recipient's mailbox. The recipient's DN is used to route the message.

As shown in the following illustration, a message from MarcOI is delivered to NelsJ and RoseG by the information store on the same server.


Routing to a Different Server in the Same Site

When the recipient is not on the same server as the originator, the MTA uses the recipient's DN to determine the location of the server and routes the message to the other Microsoft Exchange Server MTA. The MTA delivers the message to the information store.


Routing to a Different Site or Foreign System

Messages sent to recipients in other sites or systems are delivered through connectors. Understanding how routing works helps you determine how many connectors to use and how to configure them for efficient delivery. The Microsoft Exchange Server MTA can route messages to the following:

  • Another Microsoft Exchange Server MTA in a different site using a Site Connector or a Dynamic RAS Connector.
  • A remote X.400 MTA using the X.400 Connector.
  • Other connectors or gateways that connect to foreign systems, such as the Microsoft Mail Connector or the Internet Mail Connector.

Two processes are used to determine which connector a message is sent through: routing determines all the connectors that can deliver the message and selection determines the most efficient connector to use.

Connector Routing

Messages to other systems are routed using the appropriate address for the system, such as an SMTP address for a message traveling through the Internet.

Each connector has at least one address space and can have one or more connected sites associated with it. Address space and connected sites information is defined on the Address Space and Connected Sites property pages in the Microsoft Exchange Server Administrator program. These associations create the Gateway Routing Table (GWART). The GWART is replicated throughout the organization, so each server is aware of all possible routes.

When a message is sent, the MTA compares the recipient's address type with the GWART to determine the connectors that can deliver the message. There are three groups of address types.

Distinguished Name (DN) This address type is only searched when a DN for the recipient is found in the directory. This Microsoft Exchange Server address type is EX.

Domain Defined Attribute (DDA)

The DDA is the format for a custom recipient address. The address types MS and SMTP are created automatically. Other DDA addresses can be used with custom or third-party gateways.

O/R Address

This is the X.400 address. The address type is X400.

Each line of the GWART indicates an available path the MTA can use to route messages. The MTA scans the GWART to find an address space that matches the recipient's address and chooses connectors with address spaces similar to the recipient's address. You can view the contents of the GWART, including the address type each connector routes, in the Routing property page of the Site Addressing object as shown in the following illustration.

If more than one connector can send the message, a connector selection process determines the most efficient connector to use. If no connectors can service the address space, the message is returned to the originator as nondeliverable.

Connector Selection

A selection process is used to identify the connector that can most efficiently deliver the message. Each time a connector or group of connectors meets the connector selection criteria, it is passed to the next step. Each of these steps applies to MTA-to-MTA connections, which includes the X.400 Connector, the Dynamic RAS Connector, and the Site Connector. Connectors and gateways for foreign systems are chosen based only on the address spaces they process and the address space cost. You can influence which connectors are chosen by adjusting some of the settings used in the process.

The following illustration shows the steps the MTA uses to select a connector.

A description of each step follows.

Comparing open retry count to max open retries

The open retry count is the number of times the MTA has attempted to transfer a message using a specific connector. Max open retries is a setting on each connector, except foreign system connectors. It specifies the number of times a message can attempt to be transferred through that connector. Connectors that have an open retry count less than the max open retry value are chosen.

Choosing active connectors

Site Connectors, Internet Mail Connectors, and Microsoft Mail Connectors are always active. X.400 Connectors and Dynamic RAS Connectors have activation schedules. There are four settings for the activation schedules: active now, active in the future, never active, and remote initiated.

All active connectors are chosen first, and then a group of connectors that will become active next is chosen. If no connectors are active and none will become active, connectors that are initiated remotely are chosen.

Choosing connectors with low retry counts

The open retry count starts when the connection to the remote MTA fails. The connector attempts to establish the connection again when the open retry timer expires. The number of times the connector attempts the connection is based on how the max open retries setting is configured. The open retry counters are compared to each other, and connectors with the lowest number of open retries are chosen.

Choosing connectors that have not failed

Each MTA maintains an open retry timer for each connector that is on the same server. Connectors on other servers skip this step. The open retry timer begins as soon as a connection fails. Any connector that is not in a retry state is chosen. The open interval value determines how long the connector waits before attempting the connection again. This prevents the MTA from routing a message to a connector that failed the last time it tried to establish a connection.

For example, if you are using a Site Connector and Dynamic RAS Connector and the local area network (LAN) is down, a message is routed to the Site Connector because it has a lower cost. The connection fails because the LAN is down so the message is routed to the Dynamic RAS Connector. The next message to arrive before the open retry timer expires on the Site Connector is routed directly to the Dynamic RAS Connector.

Comparing costs

You specify costs when the address space is determined for each connector. Connectors with the lowest cost are chosen first.

Choosing local connectors

A local connector can send the message directly to the remote site, as in a messaging bridgehead server. Remote connectors require the MTA to pass the message to a messaging bridgehead server before the message can be passed to the remote site. Using local connectors reduces the need for additional processing power and increased bandwidth required to transmit the message.

Load Balancing

If more than one connector is chosen to deliver a message, load balancing is implemented. In load balancing, one of the connectors is chosen randomly, rather than by queue size, message size, or other variables.

If more than one Site Connector is selected, the MTA chooses a connector based on cost. Target MTAs with a cost of 0 are tried first, and target MTAs with a cost of 100 are tried last. Random selection is used only after all target MTAs with a cost of 0 have been tried. All target MTAs are tried before the message is rerouted. You can influence which Site Connectors are used more frequently by adjusting the cost value assigned to each connector.

For more information about using target MTAs and connection costs, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server Administrator's Guide.

Rerouting and Retries

If the message is not sent to the connector, the MTA attempts to reroute the message. When a message is rerouted, the MTA performs routing and selection again to find the most efficient connector.

When a message is sent to a connector or gateway for a foreign system, such as the Microsoft Mail Connector or the Internet Mail Connector, the MTA considers the message delivered when it reaches the connector. Rerouting does not occur, even if the foreign system connector cannot deliver the message.

A message routed to a connector with an activation schedule of never active or remote initiated is not rerouted unless the activation schedule is changed while the message is waiting to be delivered.

The max transfer retries and transfer interval settings in the Override property page for the Site Connector, Dynamic RAS Connector, and X.400 Connector determine how many times and at what interval the MTA sends a message through the connector. A retry count is stored on each message for each connector that has been tried.

When a message is routed to a connector that fails to connect to the other MTA, the retry count is incremented and the message is immediately rerouted. If the message cannot be delivered after all the connectors have been tried, the message is returned with a non-delivery report (NDR).


Chapter 7 Security

People who send and receive e-mail rely on their messaging systems to provide reliable and secure service. The following types of attacks can compromise the security of e-mail systems:

  • Theft of or tampering with data. By "sniffing" packets or intercepting messages in transit on the network, an attacker can get access to data or even modify it.
  • Forgery. An attacker can forge messages to appear as if they came from someone else to distribute false information or trick users into sending them sensitive data.

E-mail systems are also susceptible to the following kinds of attacks if they connect to the Internet:

  • Denial of service. Since processing messages requires disk and CPU resources on your server and bandwidth on your Internet connection, an attacker can tie up your system or network by flooding it with mail.
  • Trojan horses and viruses. Unsuspecting users can run programs they receive in messages, that can infect the system, delete files, or cause damage in other ways.

Microsoft Exchange Server provides a variety of features that you can use to ensure that your users' mail and your system are secure. You can protect messages using advanced security (encryption and digital signatures). You can ensure that communication between clients and servers is secure by configuring encrypted remote procedure calls (RPCs). You can also configure your server's hardware and software to protect your system from intrusion from the Internet.


Using Advanced Security to Secure Messages

If your organization has installed the Key Management component on a Key Management (KM) server, you can use advanced security. Advanced security allows users who need to send and receive confidential messages to digitally sign and encrypt them. It provides a higher degree of protection than built-in features such as message sensitivity, which marks messages as personal, private, or confidential. Advanced security actually prevents messages from being tampered with.

Advanced security uses industry standard cryptography methods to provide the following benefits.

Digital signatures

Ensures that messages aren't modified during transit. They also prevent forgeries by allowing users to place the equivalent of their signatures on messages. The recipient can then be certain that the message originated from the sender.

Data encryption

Provides confidentiality by ensuring that only the intended recipients can read a message.

Organizations that use advanced security to protect highly sensitive information should understand aspects of advanced security such as how it works so they can be confident that Microsoft Exchange Server provides the level of protection users need for their messages.


How Advanced Security Works

Both digital signatures and encryption are based on encryption technology. Encryption scrambles (encrypts) a message so it can't be read until it's unscrambled (decrypted) by the intended recipient. This process of encrypting and decrypting messages is called cryptography.

Microsoft Exchange Server can scramble a message or revert it to its plaintext format by applying a mathematical formula, called an algorithm, to the message. The algorithm is used with a key, which is a random string of bits that is used to lock and unlock (encrypt and decrypt) the message. Only the user who has the correct key can encrypt and decrypt the message.

Microsoft Exchange Server advanced security is called a "hybrid" encryption system. It takes advantage of two different encryption technologies: public key cryptography and secret key cryptography (sometimes called symmetric key cryptography).

Microsoft Exchange Server uses complementary elements of these technologies to digitally sign and encrypt messages. For example, Microsoft Exchange Server takes advantage of the strengths of public key cryptography to securely distribute keys between people. However, it relies on secret key cryptography to encrypt the content of messages because those operations are best suited to bulk data encryption.

Public Key Cryptography

Developed by the RSA Corporation, public key cryptography is based on two halves of the same key that are "mirror images" of each other. The two halves of the key are called a key pair. One or the other key in the key pair is required to encrypt and decrypt a message. Microsoft Exchange Server uses two key pairs that can be assigned to a user. One key pair is used to digitally sign messages, and the other is used to encrypt messages.

A key pair consists of a public key and a private key. The public key is publicly known and stored in the directory so everyone can access it. The private key is known only to the key's owner and is stored in the user's security (.epf) file. By making one key publicly available and the other key secret, public key cryptography simplifies the distribution of keys without compromising their security. For example, a message encrypted with a recipient's public key can be decrypted only with the recipient's private key.

Public key cryptography is computationally slow. Therefore, it's not as effective as secret key cryptography for encrypting large amounts of data. As a result, Microsoft Exchange Server uses public key cryptography primarily for digital signatures and to exchange secret keys securely between users.

To prevent keys from being tampered with after they've been created, Microsoft Exchange Server uses certificates to establish a trust of keys. A certificate is a user's public key that has been digitally signed by a trusted authority called a Certification Authority (CA). The KM server is a type of CA. Because the KM server uses its private key to sign certificates, a certificate's signature can be verified using a copy of the KM server's public signing key that resides in every user's security file.

In Microsoft Exchange Server, encryption and signing operations use different certificates. Signing certificates are sent with every signed message. This ensures that the recipient can verify a sender's digital signature even while offline. In contrast, encryption certificates are available in the global address list so everyone has access to them. Users can make encryption certificates available while offline by downloading a copy of the offline Address Book with full details.

Microsoft Exchange Server uses a certificate format that complies with the public X.509 standards.

Secret Key Cryptography

Unlike public key cryptography which uses key pairs, secret key cryptography encrypts and decrypts messages using an algorithm with a single key. A secret key is a key that both the sender and recipient know. It's similar to a password that you use to log on to a server. Both you and the server must know the same password for you to have access to the server.

Because the secret key must be distributed to both the sender and the recipient in such a way that it still remains a secret, key distribution is more difficult with secret key cryptography than public key cryptography. However, secret key cryptography is very fast and is ideal for encrypting and decrypting large amounts of data. As a result, Microsoft Exchange Server relies on it to encrypt the contents of messages, including body text and attachments.

Microsoft Exchange Server uses several different types of secret key encryption algorithms to comply with U.S. export laws, including the Data Encryption Standard (DES) and the CAST encryption algorithms. For information about selecting the encryption type best suited for your organization, see "Selecting an Encryption Type" later in this chapter.

DES

A secret-key algorithm based on a fixed-length, 56-bit key. It was first published by the National Bureau of Standards. DES is a U.S. Federal information processing standard that is available only with the North American version of Microsoft Exchange Server.

CAST A secret-key encryption method originally developed by Carlisle Adams and Stafford Tavares of Northern Telecom Research (CAST is formed from the initials of their first and last names). CAST provides flexible encryption standards by allowing a variable key between 40 and 128 bits. The key is a number, specified in bit length that is used to encrypt data. Longer keys are more secure than shorter ones. Microsoft Exchange Server uses CAST 40, which uses a 40-bit key, and CAST 64, which uses a 64-bit key. CAST 64 is available only with the North American version of Microsoft Exchange Server.

Key Management (KM) Server

The Key Management (KM) component is an optional Microsoft Exchange Server component that is installed on an organization's KM server. It provides centralized administration and management of public keys and certificates and is used to set up advanced security.

The KM server performs a variety of important tasks, including generating public and private encryption keys. It also acts as your CA by creating public signing and encryption X.509 certificates. Once the KM server has generated keys and certificates and a user's security file has been created, the KM server doesn't need to be running for a user to send and receive encrypted and signed messages.

The KM server also maintains a secure copy of every user's private encryption key in an encrypted database in case the key needs to be retrieved after it's been issued. For example, if a user is terminated or leaves the company, the KM server enables an authorized administrator to recover the user's encrypted messages by recovering the user's private keys. You can also recover keys for users when they lose their security (.epf) file or forget their security file password.

Another important function of the KM server is maintaining and distributing a certificate revocation list (CRL). The revocation list enables you to revoke a user's certificate if a user's keys are compromised and no longer secure. It is stored in the directory on every server. A replica of the revocation list is also kept on the Microsoft Exchange Client computer so certificates can be checked while working offline. When you decrypt a message or verify its signature, the revocation list is checked to make sure that the certificate hasn't been revoked. If it has, the user is warned that the sender has been revoked from the organization. For more information about revocation, see the Microsoft Exchange Server Concepts and Planning Guide.

Digital Signatures

A digital signature is similar to a person's handwritten signature that can be used to authenticate a sender's identity and ensure that a message isn't modified during transit. It's a string of bits, called a message hash or checksum, that's calculated and then added to a signed message. Every message has a unique signature or checksum that's generated by applying a 128-bit RSA algorithm called Message Digest 5 (MD5) to the message.

Microsoft Exchange Server relies on public key cryptography to ensure the authenticity of digital signatures. When the user signs a message using the Microsoft Exchange Client, the checksum of the message is encrypted using the sender's private signing key. When the recipient verifies the message's signature using Microsoft Exchange Client, the sender's public signing key is used to decrypt the checksum and verify the sender's identity. The signature on a message is valid only if the public and private keys correspond to each other.

Microsoft Exchange Server determines the integrity of a signed message by comparing the checksum on the message with a new checksum of the message that the recipient's client generates. If the two checksums are identical, the message hasn't been modified since it was signed. However, if even one bit in the message has been changed, the messages will have different checksums and the recipient is notified that someone tampered with the message. Encrypting the checksum using the signer's private key also ensures that a signed message can't be tampered with because the checksum on a message can't be switched without the signer's private key.

Signing a Message

When a user signs a message, the Microsoft Exchange Client generates a checksum of the message and adds it to the message. The checksum (digital signature) is then encrypted using the sender's private signing key. Finally, the original plaintext message, the digital signature, and the sender's signing certificate (which contains the sender's public signing key) are sent to the recipient.

The following illustration describes the steps in the process.

Verifying a Signature on a Message

When a recipient verifies a message's signature, the Microsoft Exchange Client checks the sender's signing certificate against the CRL. If it is on the list, the recipient is warned that the sender has been revoked from the organization. The encrypted checksum (digital signature) is decrypted using the sender's public signing key that was sent with the message. Finally, the client generates a checksum on the plaintext message so it can be compared with the checksum that was just decrypted. The two checksums should be the same. If they are not, the recipient is warned that the message has been altered since it was originally signed.

The following illustration describes the steps in the process.

Message Encryption

When a message is encrypted, the Microsoft Exchange Client generates a random secret key called a bulk encryption key, which is used to encrypt the message. The recipient's public encryption key is then used to encrypt the bulk encryption key in a lockbox. The lockbox allows the random bulk encryption key to be transmitted securely to the recipients. If an encrypted message is sent to several people, each recipient's public encryption key is used to generate a different lockbox, but the message contents are encrypted only once.

Encrypting a Message

When a sender encrypts a message, the Microsoft Exchange Client retrieves a certificate for each message recipient from the global address list. A bulk encryption key is then randomly generated and used to encrypt the contents of the message. Each recipient's public encryption key is then retrieved from the recipient's certificate and used to encrypt the bulk encryption key in a lockbox. Finally, the lockbox and the encrypted message are sent to the recipient.

The following illustration describes the steps in the process.

Decrypting a Message

When a recipient decrypts a message, Microsoft Exchange Server retrieves the recipient's private encryption key from the recipient's security (.epf) file. The recipient's private encryption key is then used to decrypt the lock box. Finally, the bulk encryption key contained in the lock box is used to decrypt the message.

The following illustration describes the steps in the process.


Selecting an Encryption Type

Microsoft Exchange Server supports three different secret key algorithms, including DES for 56-bit encryption and CAST 40 and CAST 64 for 40-bit and 64-bit encryption. The type of encryption you implement in your organization depends on the level of security your organization requires and whether you are using an international or North American version of Microsoft Exchange Server. Organizations that require strong encryption should use either DES or CAST 64.

As you determine the type of encryption that is appropriate for your organization, keep in mind the following:

  • How secure the different types of encryption are.
  • International considerations for using Microsoft Exchange Server.
  • How to move messages from one encryption type to another.

Encryption Security

An encrypted message is only as secure as the algorithm that's used to encrypt it. The security of an encryption algorithm is measured by how easy it is to find weaknesses in the algorithm that allow someone to decrypt a message without its key. The most secure algorithm is one that can be cracked only by trying every possible key combination, which could take many lifetimes depending on the length of the key. The algorithms chosen for Microsoft Exchange Server, including DES and CAST, have been studied extensively by cryptography experts and have no known methods of attack other than a brute-force approach of trying every key.

Algorithms that use longer keys are generally more secure than algorithms that use shorter keys because there are more possible key combinations. For example, since a 64-bit key is a bigger number than a 40-bit key, 64-bit encryption is approximately 16 million times more secure than 40-bit encryption and takes 16 million times longer to crack. In Microsoft Exchange Server, cracking the key for one message doesn't crack the key for another message because every message is encrypted with a unique key.

International Considerations

International versions of Microsoft Exchange Server are available only with CAST 40 encryption because of U.S. export restrictions that limit the strength of cryptographic systems shipped outside the U.S. Currently, DES and CAST 64 are available only in versions of Microsoft Exchange Server sold in the U.S. and Canada. Some countries, such as France, have their own restrictions on the use of cryptography. For example, Microsoft Exchange Server advanced security can't be used in France.

International organizations that use Microsoft Exchange Server in a variety of countries can mix and match more than one type of encryption. This is possible because Microsoft Exchange Server maintains information in the directory about the type of encryption that is supported for every user in the organization. If a message is addressed to multiple recipients who are using different types of encryption, Microsoft Exchange Server automatically attempts to encrypt the message using the type of encryption that all recipients share. For example, if a message is addressed to a recipient using CAST 40 and another recipient using CAST 64, the message will be encrypted using CAST 40. If a message is addressed to a recipient who is not using advanced security, Microsoft Exchange Server allows the user to either not send the message to that recipient or send the message in plaintext format.

United States Legal Considerations

Current U.S. State Department export regulations prohibit the export of software containing strong encryption outside the U.S. and Canada. To help administrators in the U.S. comply with these regulations, the Microsoft BackOffice Resource Kit: Part One includes a form for temporarily exporting encryption products. You can use this form if you're traveling outside the U.S. with a laptop that uses advanced security with the Microsoft Exchange Client. For more information, see the Tools directory on the Microsoft BackOffice Resource Kit: Part One compact disc.

Moving Messages to Another Encryption Type

If users move to another location within your organization that uses a different type of encryption, they can transfer their encrypted messages from one type of encryption to another using the Bulk Advanced Security tool (Sectool.exe). For example, a user transferring from an office in the U.S. to Britain can use Sectool.exe to convert encrypted mail from CAST 64 to CAST 40.

The following describes the steps to follow when using Sectool.exe. For more information about using the tool, see the online Help for Microsoft Exchange Server Resource Kit Tools (Exchtool.hlp) that is included on the Microsoft BackOffice Resource Kit: Part One compact disc.

  • Use Sectool.exe to decrypt your messages.
  • Copy your messages to a personal folder (.pst) file.
  • At your new Microsoft Exchange Client, copy your .pst file to your local disk and add it to your messaging profile.
  • Use Sectool.exe to encrypt the messages again in the .pst file with the new encryption type.
  • (Optional) Copy the messages from the .pst file to your mailbox on the server.


Increasing Microsoft Exchange Server Security

In addition to using advanced security to protect messages, you can also increase the security of your Microsoft Exchange Server system by:

  • Restricting access to resources by setting permissions on directory objects and public folders. For information about setting permissions, see Appendix D, "Setting Permissions."
  • Changing permissions on shared directories created during server Setup to minimize the possibility that Microsoft Exchange Server files can be tampered with.
  • Configuring Microsoft Exchange Client to use encrypted RPCs so data sent between clients and servers can't be altered while traveling across the network.


Changing Permissions on Shared Directories Created During Setup

When Microsoft Exchange Server is installed, Setup creates several shared directories so other Microsoft Exchange Server computers can access the files in the directories. By default, Setup sets permissions on these directories that are sufficient for most organizations. However, you can change the permissions if you are concerned that the default permissions on these directories don't give the files enough protection against attacks by unauthorized users.

Caution

You should change permissions on these directories only if necessary because changes could damage your Microsoft Exchange Server system.

Setup creates the following shared directories:

Directory | Description
Add-ins | Contains files that the Administrator program uses to display information about connectors. This directory is shared as Add-ins.
Address | Contains files for creating e-mail addresses. This directory is shared as Address.
Connect | Contains files for Microsoft Exchange Server connectors. This directory is a hidden share that is shared as connect$.
Connect\Msmcon\Maildata | Contains files used for Microsoft Mail. This is a hidden share that is available only if the Microsoft Mail Connector is installed. It is shared as maildat$.
Res | Contains files, such as logs for Event Viewer and Windows NT Performance Monitor, used by the local computer and remote computers. This directory is shared as resources.
Tracking.log | Contains files used for message tracking. This directory is shared as tracking.log.

The following permissions are granted to these directories:

Permission | Type of access
Everyone | Read (except for Maildata, which has full control)
Service account | Full control
Local administrators | Full control

To restrict access to the shared directories, remove the Everyone permission and give permissions to specific accounts using File Manager. Use the following guidelines for restricting access on shared directories.

  • Only administrators responsible for message tracking should have permissions for the Tracking.log directory because it may contain sensitive information about messages.
  • You can give other administrators permissions to the Add-ins, Address, Connect, and Res directories. Only administrators that need to administer the Microsoft Mail Connector should have permissions on Maildata. If you are using the Microsoft Mail External program for message transfer, also give the account for this program permissions for the Maildata directory.
  • Do not change permissions for the service account and local administrators because this can have unpredictable results.


Configuring the Microsoft Exchange Client to Use Encrypted RPCs

Microsoft Exchange Client computers and Microsoft Exchange Server computers communicate using Windows NT Server remote procedure calls (RPCs). To increase the security of data communication between clients and servers, Microsoft Exchange Server enables users to take advantage of the built-in RPC security feature called encrypted RPC. Microsoft Exchange Client can be configured to use encrypted RPCs so communication between clients and servers is secure and messages can't be tampered with during transit.

Encrypted RPC uses a 40-bit RSA algorithm called RC4 to encrypt data while it is on the network. Once the data reaches the destination computer, it is no longer encrypted. Encrypted RPCs provide increased security for messages sent on internal networks, as well as outside organizations, for example, to the Internet.

Encrypting RPCs is different from encrypting a message using advanced security. Encrypted RPC provides protection for data only while it travels on the network from point to point. A message encrypted using advanced security is protected until the recipient decrypts it using Microsoft Exchange Client, regardless of how many hops are used during delivery.

To configure encrypted RPCs

1. From the Tools menu in the Microsoft Exchange Client, choose Services.

2. In the list of information services, select Microsoft Exchange Server, and then choose Properties.

3. Select the Advanced tab.

4. Under Encrypt information, select both options to encrypt all client/server communication.


Increasing Security When Connecting to the Internet

Any system that is accessible through the Internet is subject to attempts to infiltrate the operating system's security or to exploit security weaknesses of services running on the system. Administrators should be concerned not only about these kinds of blatant attacks but also inadvertent actions by users. Some of the most serious breaches in security are caused by users who release sensitive data or cause a flood of mail from the Internet.

If you are using the Internet Mail Connector, you should consider how you will minimize the security risks when connecting Microsoft Exchange Server to the Internet. You can configure Microsoft Exchange Server and Windows NT Server to ensure that people in your organization can send and receive Internet mail but unauthorized users can't access your system from the Internet. You can also set up other mechanisms such as firewalls that protect against attacks.


Using Firewalls

Firewalls are one of the best ways to protect your system from attack by users on the Internet. You can use a firewall to separate your internal network from the Internet. It restricts inbound and outbound access, and can analyze all traffic between your network and the Internet. A firewall can range from a simple packet filter to complex bastion hosts that analyze traffic for each application type. A bastion host is any computer that must be secured because it is accessible from the Internet and exposed to attack. A firewall can be a single router or computer, or it can be a combination of components such as routers, computers, networks, and software.

There are several types of firewall software and hardware you can use to protect your organization from outside attacks, including:

  • Proxy servers
  • Dual-homed systems
  • Packet filtering
  • Firewall software
  • Domain Name Service (DNS)

Using Proxy Servers

Some services, such as Web and File Transfer Protocol (FTP), are point-to-point so that a client can make a connection directly to a server. Allowing clients inside your network to connect directly to hosts on the Internet is generally unsafe. One solution is to use a proxy server (also called an application-level gateway) to interact with external servers on the client's behalf. The client talks to the proxy server, which relays approved client requests to servers and relays responses back to the client. External hosts do not connect directly to clients in your network.

Microsoft Exchange Server and many other e-mail systems use a store-and-forward design, which uses a proxy mechanism. Clients connect to servers that reside on the local network. Servers then communicate with each other to transfer e-mail messages. Separate proxy services are unnecessary if Microsoft Exchange Server is configured correctly.

Using Dual-Homed Systems

One way to set up a bastion host is to use a dual-homed computer, which has a connection to two networks, but does not route packets between them. One connection is to your internal network to allow communication with other servers and clients. The other connection is to the Internet. You can run Microsoft Exchange Server on a dual-homed computer to provide e-mail connectivity to the Internet safely.

Using Packet Filtering

Implementing a packet filter between the Internet and your network can add a layer of security. You can use a packet filter, such as a screening router, to control the ports and Internet Protocol (IP) addresses to which external systems can connect. However, if an intruder is able to get past the router, your network is open to attack.

To minimize this risk, many organizations implement a perimeter network. This is a network that is connected to the Internet through an external screening router and to the internal network through an interior screening router. Computers that are connected to the perimeter network have limited access to both the Internet and the internal network. This can be a convenient architecture if multiple servers require direct Internet access.

This configuration provides three levels of defense. If the external router and a bastion host on the perimeter network are compromised, the attacker does not gain unlimited access to your internal network because the internal router is controlling access.

Using Firewall Software

There are many commercial firewall products that provide proxy services. Some of these support simple mail transport protocol (SMTP) e-mail. There are also free implementations of SMTP proxies, such as smap, which forward messages between internal and external systems. These products are not likely to have security weaknesses because they are typically designed solely for security purposes. Furthermore, they are typically a simple implementation with restricted functionality. However, a disadvantage of firewall software is that different SMTP servers must be managed. If your internal SMTP server is upgraded with new features, the firewall software must also be upgraded.

Since Microsoft Exchange Server provides secure Internet access, additional firewall software is unnecessary. However, the Internet Mail Connector can be used with firewall software if desired. To do so, you should configure your Internet Mail Connector to forward all mail to the bastion host running the firewall software.

Using DNS

DNS is a distributed database that translates between host names and IP addresses. It also carries other information about hosts, such as mail exchanger (MX) records that specify one or more hosts that will accept mail for a domain. When a client needs to find out information about another host, such as the IP address for mail.acme.net, it queries its local DNS server for that information. The local DNS server responds if it has the information. If it doesn't, then the local DNS server queries other DNS servers until it either finds the information or runs out of places to look. This forwarding of the query is transparent to the client, which connects only to the local DNS server.

If your system accepts mail directly from other hosts on the Internet, it should be listed in the DNS. A DNS MX record should be created that routes all mail sent to your registered domain to the host(s) that process incoming mail. Unless you plan to forward all outbound Internet mail to a relay host (a host outside your organization that has better e-mail connectivity), your server will also need to be able to query DNS to route messages to the proper destinations. You may have your Microsoft Exchange Server computer configured to use DNS services from your Internet service provider, or you may have your own DNS servers. If you maintain your own DNS servers, they must be registered with your parent domain.

If you are using DNS and do not want DNS queries from the Internet to return information about computers on your internal network, you should configure DNS so that external hosts can query for information about your Internet server(s), but not about any other hosts. To do this, you must set up a pair of DNS servers.

One server is an external DNS server, which you register with your parent domain and configure with address and MX records for your bastion hosts. You also set up an internal DNS server to be used by clients on your network. This DNS server should be configured to forward queries it cannot resolve to the external DNS server, so clients in your network can resolve Internet host names. Your bastion host should also use the internal server for DNS so it can resolve both internal and external names. Since the external DNS server does not have complete information for your internal network, and your internal DNS server cannot be accessed from the Internet, you can hide most of your computers from external DNS queries by not creating records for them on the external DNS server.


Securing Your Internet Connection

You can take advantage of a variety of features provided with Windows NT and Microsoft Exchange to prevent attackers from damaging your system over the Internet.

Configuring the Internet Mail Connector

You can enhance security when connecting to the Internet by configuring the following on the Internet Mail Connector. For information about how to set these options, see the Microsoft Exchange Server Administrator's Guide.

Reject messages by IP address

By default, the Internet Mail Connector accepts incoming connections from any IP address. If your Internet Mail Connector needs to communicate only with specific SMTP hosts, you can configure it to reject connection attempts from other IP addresses. This makes it more difficult for someone to mount an attack from the Internet against your system.

Set message size limits You can establish message size limits for the Internet Mail Connector. The default limit applies to both incoming and outgoing mail. If an incoming message from another SMTP host exceeds the size limit, the Internet Mail Connector stops writing data to disk and discards any remaining data. This prevents large messages from filling up the disk on your server, which helps reduce the impact of a denial-of-service attack.

Disable auto-replies to the Internet

The Internet Mail Connector can prevent delivery of automatically generated replies, such as out-of-office replies. When users set up out-of-office replies using Microsoft Exchange Client, they frequently include a number where they can be reached and other information. In some cases, this information should not be shared outside the organization. You can configure the Internet Mail Connector to disable outbound delivery of automated replies globally or by domain.

Set delivery restrictions

You can restrict which users in your organization have permission to send mail through the Internet Mail Connector. For example, you can grant Internet mail access to full-time employees. You can grant or deny Internet mail access to users by configuring the Internet Mail Connector Delivery Restrictions property page in the Administrator program.

Protecting User Accounts

To ensure that someone can't gain access to your system by impersonating a user, use passwords on user accounts that are difficult to guess. This is especially important for accounts with administrative permissions. You should also limit the number of accounts that are granted administrator permissions.

Using Windows NT File System (NTFS)

You can use Windows NT file system (NTFS) to restrict access to your files and directories and limit the amount of damage an intruder can do if they gain access to a user account. You can also enable auditing of NTFS files and directories through the File Manager. This produces audit records you can periodically review to ensure that no one has gained unauthorized access to sensitive files.

Using and Configuring Services

You should run only essential services on the server and disable any unnecessary services. If fewer services are running, it's less likely that there will be a mistake in the service's configuration that an attacker could exploit.

You should also unbind unnecessary services from network adapters that are connected to the Internet. To do this, choose the Network icon in Control Panel, and then choose Bindings. For example, you can use the Server service to copy files from computers in your internal network, but you might not want remote users to have direct access to the Server service from the Internet. To use the Server service on your private network, you can disable it from binding to any network adapter cards. You can use the Windows NT Server service over the Internet; however, you should understand the security implications and licensing issues of using this configuration.

TCP/IP is the only protocol you need to bind to the network adapter card connected to the Internet. Make sure routing is disabled, so your internal network is isolated from the Internet.

If you decide to bind the Server service to the Internet adapter card, then double-check the permissions for your network shares and the permissions for the files in the shared directories.

Connecting to SMTP Hosts with the Internet Mail Connector

You can set up a Microsoft Exchange Server with the Internet Mail Connector on your bastion host that routes mail between your organization and SMTP hosts on the Internet. To minimize risk, you can make this a dedicated Internet mail server that doesn't contain user mailboxes. If an intruder does gain access to the bastion host, none of the data stored in user's mailboxes or public folders will be at risk because only messages in transit are stored at the bastion host.

If you are using a packet filter, you must configure it to allow TCP connections to and from port 25 on the Microsoft Exchange Server.

Connecting to X.400 MTAs with the X.400 Connector

RFC-1006 defines a mechanism for applications defined on the ISO protocol suite to run over TCP/IP. X.400 MTAs can use this mechanism to communicate over the Internet. If you are using a packet filter, you must configure it to allow TCP connections to port 102 on the Microsoft Exchange Server computer. Note that with X.400 authentication, passwords are protected.

Connecting Sites Using the Internet

You can use the Internet Mail Connector, the X.400 Connector, or the Site Connector to connect Microsoft Exchange Server sites through the Internet. If mail must pass through one or more SMTP hosts to reach its destination, the Internet Mail Connector must be used. Note that data is not encrypted when it is sent through these connectors unless messages are encrypted using advanced security.

The Site Connector uses RPCs to communicate between servers but does not use RPC encryption. If you use a packet filter, you must configure it the same way as you would to enable client access over the Internet.

Configuring DNS

If you are using DNS with a packet filtering router, you must configure the router to allow user datagram protocol (UDP) and TCP connections to port 53 on the DNS server.


Enabling Clients to Securely Connect over the Internet

Microsoft Exchange Client computers can connect to mailboxes on Microsoft Exchange Server computers remotely using TCP/IP over the Internet. By connecting over the Internet, users can read and send mail just as if they were on the same local area network (LAN) as the server. For example, if users from CompanyA need to access mail while visiting CompanyB, they can use CompanyB's Internet connection. Microsoft Exchange Client doesn't need to use a modem or Remote Access Service (RAS) to establish a remote connection with Microsoft Exchange Server. However, both the client and the server must support TCP/IP.

You can enable communication over the Internet with the least amount of security risk to your organization by performing these tasks.

  • Configure the Microsoft Exchange Client to use encrypted RPCs. This ensures that messages transmitted over the Internet between a client and a server are secure and can't be tampered with. For more information about configuring encrypted RPCs, see "Configuring the Microsoft Exchange Client to Use Encrypted RPCs" earlier in this chapter.
  • Specify the client's home server using the server's fully qualified domain name. This enables the Microsoft Exchange Client to locate the home server.
  • If the home server is in a different domain from the user account accessing the mailbox, enable the client to be authenticated by the home server's domain. This gives the user access to the domain where the home server is located.
  • If your organization uses an Internet firewall, configure the firewall to allow RPC communication. If a firewall is not used, RPC communication to the Internet is enabled by default.

Specifying the Home Server

To connect to a Microsoft Exchange Server computer remotely over the Internet, the client must use the server's fully qualified domain name. This is because the server name must be in a format that can be resolved over the Internet. Instead of connecting to a server using its computer name (also called a NetBIOS name) as the client on a LAN does, you must specify a name such as server1.acme.com. If the server name is not registered in DNS, you can specify the IP address instead.

To specify the home server name

1. In Control Panel, choose Mail, select Microsoft Exchange Server, and then choose Properties.

2. Under Microsoft Exchange server, type the name of the server that contains the mailbox you want to use.

3. Choose OK.

Configuring Authentication by the Home Server's Domain

When users connect to a server using the Internet, they will probably be in a different organization that uses a different domain from their home server. To ensure that the client is authenticated by the server's domain during a remote Internet connection, the user must connect to the home server using a user account that is valid in the home server's domain. To make connecting to the home server easier, the Microsoft Exchange Client can be configured to prompt the user for the name and password of the user account in the home server's domain.

To enable the client to be authenticated by the home server's domain

1. In Control Panel, choose Mail, select Microsoft Exchange Server, and then choose Properties.

2. Select the Advanced tab.

3. Clear Use network security during logon.

4. Choose OK.

Configuring a Firewall to Allow RPC Communication

In order for Microsoft Exchange Client computers to access Microsoft Exchange Server computers remotely over the Internet, the clients and servers must be able to communicate using RPCs. If you are not using an Internet firewall, RPC communication is enabled by default. This configuration is risky because an attacker can gain access to the server and potentially compromise the security of Microsoft Exchange Server resources such as mailboxes and public folders.

If you are using a firewall to increase your system's security, you may need to configure the firewall to allow RPC communication. Some Internet firewalls do not accept TCP/IP port numbers that Microsoft Exchange Server uses for RPC communication. To solve this problem, you should add port 135 to your firewall and configure Microsoft Exchange Server to use the same ports as your firewall.

To configure Microsoft Exchange Server, you should set two unique port numbers, one for the information store and one for the directory. The registry value TCP/IP Port controls this setting. This DWORD value is a 16-bit number that you set for the port that the firewall will accept.

For the directory, you can modify the port numbers in the following registry location:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeDS\Parameters\TCP/IP Port

For the information store, you can modify the port number in the following registry location:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIS\ParametersSystem\TCP/IP Port

If you are using a packet filter, you must configure it to allow TCP connections to these ports in addition to port 135 (for the RPC End-Point Mapper service) on the Microsoft Exchange Server computer.

To add TCP/IP port numbers

1. In the Windows NT registry, select one of the following keys:

  • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ MSExchangeDS\Parameters
  • HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\ MSExchangeIS\ParametersSystem

2. From the Edit menu, select Add Key.

3. In Key Name, type TCP/IP Port, and choose OK.

4. Select the new TCP/IP Port key, and select Add Value from the Edit menu.

5. In Value Name, type TCP/IP Port. In Data Type, select REG_DWORD, and choose OK.

6. In Data, type the number of the port that the firewall will accept.


Chapter 8 Optimizing Performance

There are several ways you can optimize the performance of Microsoft Exchange Server to get the most out of your system, including:

Optimizing your topology

Carefully plan how your system is set up and make sure it has adequate network bandwidth to handle the traffic between clients and servers.

Optimizing your server

Take advantage of the hardware and software resources on your Microsoft Exchange Server computer so you can provide the fastest, most reliable service to your users. Windows NT Performance Monitor and the Microsoft Exchange Server Performance Optimizer can help you understand how to optimize your server's performance.

Balancing users per server

Determine the number of users your server can support so you can achieve the level of performance you need. You can estimate usage levels and measure the expected load on the server using Microsoft Exchange Server Load Simulator (Loadsim.exe).

For information about troubleshooting performance, see Chapter 9, "Troubleshooting." For more information about optimizing performance, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server white paper Performance: Concurrent Users Per Server that is available from the Microsoft Exchange Server web site (www.microsoft.com/exchange).


Optimizing Your Topology

Aspects of your organization's topology, including how your sites and servers are laid out, the amount of traffic your system supports, and network bandwidth, can have a significant effect on overall system performance. Optimizing your topology includes planning server locations, site boundaries, and replication settings to increase the speed of directory and public folder replication and message delivery.

Some strategies for optimizing your topology's performance are:

  • Controlling the amount of traffic your system supports. For example, you can restrict the number of messages users can send or limit the size of messages. Factors that can affect traffic are the type and number of messages, the frequency of public folder replication and the size of replicated public folders, and the frequency of directory replication and the size of the directory changes.
  • Making sufficient network bandwidth available to handle the amount of traffic your system needs to support. More traffic requires higher bandwidth connections.
  • Balancing public folder replication traffic with network traffic. If many users need to access a public folder in another site, you should replicate the public folder to the local site to minimize traffic to the other site. However, if only a few users need to access a public folder in another site, users should connect to the public folder in the other site.
  • Arranging your sites in a hub-and-spoke configuration with one central spoke and multiple satellite sites. Servers in the hub site can be dedicated to message switching functions and act as a messaging transfer agent (MTA) backbone.

The bandwidth between servers in different sites is not as critical as the bandwidth between clients and servers. Network connections between clients and servers should have high bandwidth to ensure the fastest client/server response times possible. Tests performed by the Microsoft Exchange Server Performance Team have shown that 56K per second throughput is the threshold for communication within a site; however, this threshold can vary depending on your organization's traffic.

If you have a slow connection, you should consider placing the connection between two sites because communication between sites does not need to be as fast as communication within sites. Alternatively, if you don't want to administer two sites, you can connect clients to a central site over the slow connection. This configuration is most effective for a small number of clients. These two options are shown in the following illustration.


Optimizing Your Server

Your system's performance is also affected by the server's software and hardware configurations. You can minimize performance bottlenecks by adjusting software settings and balancing server hardware resources to support the expected load. You can use the Performance Optimizer to tune your server's software and the Performance Monitor to help you balance your server's hardware resources.

Before you install Microsoft Exchange Server and run the Performance Optimizer, you should optimize your disk subsystem. The following is the recommended disk configuration for a Microsoft Exchange Server computer:

  • A physical disk containing the operating system and the pagefile.
  • A physical disk for the transaction log files so they can be written to sequentially. To increase fault tolerance, you can mirror the disk containing the transaction log files.
  • A stripe set consisting of multiple physical disks for all other Microsoft Exchange Server components so the Microsoft Exchange Server databases can be accessed most efficiently.


Adjusting Software Settings

The Performance Optimizer is an essential step in maximizing your server's performance. It selects the software settings that are appropriate for your configuration and places Microsoft Exchange Server files in the best locations. It configures your server based on the following factors:

  • The number of users that the server supports and the number of users in your organization.
  • The types of activities the server will perform.
  • The server's hardware resources, including the amount of RAM, and the number and type of disks and processors.

For example, the Performance Optimizer uses the number of clients that the server will support to determine the number of database buffers to allocate for the information store.

You should run the Performance Optimizer after you run Setup or change your server's hardware configuration. In particular, you should run the Performance Optimizer after you:

  • Make changes to your server's disk.
  • Add a caching controller.
  • Change the amount of RAM.
  • Add a processor.
  • Change the number of users that the server will support.
  • Add or remove a component on the server.

Customizing Settings for Performance Optimizer

You can customize Performance Optimizer settings by typing perfwiz -v at the command prompt in the Exchsrvr\bin directory. When you run perfwiz -v, the Performance Optimizer displays two additional screens that provide the following options.

Option

Description

# of information store buffers

The number of buffers allocated to the information store. Each buffer is 4K.

# of directory buffers

The number of buffers allocated to the directory. Each buffer is 4K.

Minimum # of information store threads

The minimum number of threads within a process that the information store can initiate.

Maximum # of information store threads

The maximum number of threads within a process that the information store can initiate.

# of directory threads

The number of threads within a process that can be initiated by the directory.

Maximum # of cached categorizations

The maximum number of categorizations that the system is allowed to cache. Categorizations are generated on public folders or mailbox folders when you choose Group By from the View menu. Increasing the number of categorizations improves performance because existing categorizations can be reused. It also increases the amount of disk space used.

The maximum number of categorizations can be estimated using the following equation: the number of public folders with categorizations plus (the number of users on the server times the number of categorizations that each user has on the private information store).

Maximum # of cached restrictions

The maximum number of restrictions that the system is allowed to cache. Restrictions are sets of data generated during a Find or Filter operation on the Microsoft Exchange Client. Increasing the number of restrictions improves performance because categorizations are not constantly re-created. It also increases the amount of disk space used.

Maximum # of concurrent read threads

The maximum number of threads that the MTA can read from the directory.

# of private information store send threads

The number of threads that the private information store can use to send messages to mailboxes.

# of private information store delivery threads

The number of threads that the private information store can use to deliver messages to mailboxes.

# of public information store send threads

The number of threads that the public information store can use to send messages to public folders.

# of public information store delivery threads

The number of threads that the public information store can use to deliver messages to public folders.

# of information store gateway in threads

The number of threads that a connector or gateway can initiate to the information store when receiving messages. For best results, the server should have multiple processors if the number of threads is increased.

# of information store gateway out threads

The number of threads that a connector or gateway can initiate to the information store when sending messages. For best results, the server should have multiple processors if the number of threads is increased.


Balancing Hardware Resources

Balancing your server's hardware resources once you've installed Microsoft Exchange Server is an essential step in optimizing your system's performance. Because a server's hardware resources work together to accomplish tasks, it's not always easy to determine which resource is the performance bottleneck. If your server appears to be using a hardware resource inefficiently, another resource can actually be at fault. For example, if your server's disk is thrashing due to excessive paging, the server needs more memory, not a larger disk. For information about using Performance Monitor to help detect bottlenecks, see Chapter 9, "Troubleshooting."

The following are the four main hardware resources to consider when optimizing server performance. Guidelines for minimizing bottlenecks in these resources are described in the following sections.

  • CPU
  • Disk
  • Memory
  • Network

Balancing CPU Usage

If your server's CPU is a performance bottleneck, you can:

  • Restrict the amount or type of mail users can send.
  • Move Microsoft Exchange Server components or other applications to another server.
  • Move some or all mailboxes and public folder replicas to another server.
  • Add a faster processor.
  • If your server is a symmetric multiprocessor (SMP), add additional processors.
  • Optimize the way that the system responds to foreground and background applications. In Control Panel, choose System, choose Tasking, and then select Foreground and Background Applications Equally Responsive.
  • Upgrade to a CPU that has more Level 2 (L2) caching, particularly if the server has less than 256K of L2 cache. Some systems allow up to 2 megabytes (MB) or more of L2 memory. L2 cache is faster than RAM.

Balancing Disk Usage

If your server's disk is a performance bottleneck, you can:

  • Move Microsoft Exchange Server transaction logs to another physical disk or another physical disk that is using a different disk controller than the disk containing the databases.
  • Restrict the amount or type of mail users can send.
  • Add more RAM and run Performance Optimizer to increase the database buffers.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.

Balancing Memory Usage

If memory is a performance bottleneck, you can:

  • Add more RAM.
  • Increase the size of your pagefile. In Control Panel, choose System, and then choose Virtual Memory. Under Paging File Size For Selected Drive, set a large pagefile. You can approximate the pagefile size by adding 125 MB to the amount of physical RAM available on your server. For example, if your server has 64 MB of RAM, you should set your pagefile size to 189 MB.
  • Move the pagefile to a separate physical disk.
  • Ensure that Windows NT Server is optimized for network applications. In Control Panel, choose Network, select Server in the list of installed network software, choose Configure, and then select Maximize Throughput for Network Applications.
  • Restrict the amount or type of mail users can send.
  • Move Microsoft Exchange Server components or other applications to another server.
  • If your server is paging excessively, adjust the size of the database buffer caches by typing perfwiz -v at the command prompt. You should reduce the size of the buffer cache by 10 to 30 percent.
  • Move some or all mailboxes and public folder replicas to another server.

Balancing Network Usage

If your server's network adapter or the network is a performance bottleneck, you can:

  • Use a higher speed network type such as 100 MB per second Fast Ethernet or fiber.
  • Use a high performance network adapter and multithreaded driver.
  • Segment your network by using multiple network adapters in a single server.
  • Reduce the amount of network traffic by:
    • Optimizing your public folder replication topology.
    • Optimizing your directory replication topology.
    • Restricting the times users can log on to minimize user traffic.
  • Limiting the size of messages users can send.


Balancing the Number of Users Per Server

Definitions of users and acceptable performance vary from organization to organization. For example, a person who sends and receives a lot of e-mail may need a faster system than a user who sends mail infrequently. To help you determine the level of performance that's acceptable for your organization's users, you can use the Microsoft Exchange Server Load Simulator (Loadsim.exe).

Load Simulator can help you determine how many users your Microsoft Exchange Server computer can support. It is designed to provide a realistic load on a Microsoft Exchange Server computer by simulating the behavior of users on one or more Microsoft Exchange Client computers. It can be used for performance analysis and benchmarking or as a server stress tool.

Load Simulator takes advantage of multithreading, multiprocessing, and shared memory features in Windows NT Server to create and manage up to several hundred simulated users on a single client computer. Load Simulator makes it possible to run large server load simulations with a relatively small amount of hardware. It also provides a user interface for defining test topologies and user behavior and controlling simulations.


Requirements and Guidelines for Using Load Simulator

The following are requirements for using Load Simulator:

  • Microsoft Exchange Client running Windows NT Server or Windows NT Workstation version 3.51 or later.
  • The version of the Microsoft Exchange Client must be the same as the Microsoft Exchange Server.
  • Your client computer should have at least 32 MB of physical RAM.
  • All Microsoft Exchange Server services must be started and running on each server.
  • Directory replication must be enabled between servers in the same site.

To simulate as many users as possible on a single Microsoft Exchange Client computer, Load Simulator must use system resources efficiently. Typically, Load Simulator runs no more than 30 processes, each of which can contain one or more client threads. If you're using Load Simulator for performance analysis or benchmarking, make sure that your client hardware isn't adversely affecting performance results. Load Simulator reports that the response times for user actions should be based primarily on server load, not client hardware bottlenecks.

The particular type and number of simulated users that a Microsoft Exchange Client computer can support depends on a number of factors including your topology, hardware, and user definitions. Some important considerations are:

Network bandwidth

To run multiple simulated users on a single Microsoft Exchange Client computer, the network hardware on your client must be able to handle the number of users per computer you want to simulate. Also, you should consider running your tests on a private network so your data is reliable and reproducible.

Memory and pagefile size

Each Load Simulator process and thread uses some amount of physical RAM and virtual memory. You can use Performance Monitor to make sure your simulated users aren't using too much system memory or causing excessive pagefile activity on your client computer.

Disk I/O capacity

Some simulated user actions require disk access on the client computer. You should verify that your simulated users aren't exceeding the capacity of the disk subsystem on each client computer.


Using Load Simulator

The following procedure describes how to run a load simulation test.

To run a Load Simulator test

1. Install Load Simulator.

2. Set up your Load Simulator topology.

3. Set up distribution lists (optional).

4. Generate directory import files.

5. Create simulated users by importing them.

6. Configure multiple clients (optional).

7. Set the type of test you want to run.

8. Run the test.

When you configure and run a test, Load Simulator uses the following types of files. You can use these files to customize your test configuration or gather information about tests you have run.

.Msg files

To provide realistic user load, Load Simulator uses messages saved in .msg files. Several sample message files of different sizes and types are provided with Load Simulator. You can also create your own .msg files to have more control of their size and type.

.Sim file

Contains information about the Load Simulator configuration you specify. You can have multiple .sim files, each specifying a different configuration. Each client computer requires a .sim file to run Load Simulator tests. You should save your .sim file frequently.

.Out file

Contains the output generated by the output window.

.Log file

Contains status information about a test.


Installing Load Simulator

The following procedure describes how to install Load Simulator.

To install Load Simulator

1. Create a directory called Loadsim on your Microsoft Exchange Client computer's local disk for the Load Simulator files.

2. Copy all Load Simulator files from the Microsoft Exchange Server compact disc to the Loadsim directory on your local disk.

3. Add Load Simulator to the Microsoft Exchange program group.


Setting Up Your Topology

Before you can run a load simulation test, you must set up the mailboxes to be used for the test.

To configure your topology

1. In the Loadsim directory on your Microsoft Exchange Client computer's local disk, double-click Loadsim.exe.

2. From the Configuration menu, choose Test Topology.

3. Choose Add Server.

4. In the Server Properties dialog box, type the organization name, the site name, and the server name for each server you're testing.

5. Type in the number of user accounts you will use in the test.

To test public folder usage on the server, specify the number of public folders to use in the test.

6. Choose OK twice to close the dialog boxes.

7. From the File menu, choose Save As and save the .sim file to a directory on your local disk.

Option | Description
Organization | The organization name (up to 63 characters).
Site | The site name (up to 63 characters).
Server | The server name (up to 15 characters).
Number of accounts | The number of users that will be tested on this server.
Different public server | Another public folder server if the server containing the test mailboxes does not contain both a public and private information store.
Total public folders | The number of public folders for this test.
Root folders | The number of top-level public folders that will be used for this test.
Replicas in this site of each folder | The minimum and maximum number of public folder replicas that will be created in this site weighted to the average you select.
Replicas in other sites of each folder | The minimum and maximum number of public folder replicas that will be created in other sites weighted to the average you select.


Setting Up Distribution Lists

To use distribution lists in your test, you must configure and import them before setting up your tests. This step is optional.

To configure distribution lists

1. From the Configuration menu, choose Distribution Lists.

2. Select the Use distribution lists check box.

3. Under Distribution list specification, configure your distribution lists.

4. Choose OK.

Option

Description

Use distribution lists

Indicates whether distribution lists will be used for the test.

Size of lists

The minimum and maximum number of users that will be included in a distribution list. You can also specify an average number of users in a distribution list.

Cover % of users (no overlap)

The percentage of the total number of simulated users that are members of distribution lists.

Create lists (allow overlap)

The number of distribution lists that are created for this test.

% local to same server

The percentage of users in distribution lists whose mailboxes are located on the server that is being tested. If you don't select this option, users added to distribution lists will be chosen randomly from the total number of simulated users.

If your site has multiple servers, this option allows you to control the grouping of users in distribution lists. For example, if you set the value to 50 percent, half the users in a distribution list will reside on one server, and the other half will be randomly selected from the remaining servers in your load simulation topology.


Generating Import Files

Load Simulator stresses the server by using simulated users. It obtains the users and, if selected, distribution lists from directory import files. Before you can create simulated users, you must instruct Load Simulator to create the following directory import files.

  • A directory import file (.csv file) for each site defined in your load simulation topology. The names of these files are derived from the site name. For example, Site0.csv, Site1.csv.
  • A simple mail transport protocol (SMTP) remote user import file (-s.csv file) for each organization defined in your load simulation topology. The name of this file is derived from the organization name. For example, Org-s.csv.
  • An X.400 remote user import file (-x.csv file) for each organization defined in your load simulation topology. The name of this file is derived from the organization name. For example, Org-x.csv.

Note

If you are running tests in a single organization, you don't need to use the SMTP and X.400 import files.

To generate import files

  • From the Configuration menu, choose Generate Directory Import Files.

The directory import files are created in the default Load Simulator directory.


Creating Users

After you've generated the directory import files, you can import their contents into the Microsoft Exchange Server directory database. When you import users, Load Simulator creates a Recipients container in the directory called LoadSim.

Before you can run a load simulation test, you must import the simulated users. You can import the users and, if selected, distribution lists using Load Simulator or the Administrator program. In most cases, Load Simulator is sufficient for performing this task.

To import users with Load Simulator

  • After generating the directory import files, choose Import Users from the Configuration menu.

Load Simulator attempts directory import on a server in each of the sites defined in your topology.

You can use the Administrator program instead of Load Simulator to import users and distribution lists.

To import using the Administrator program

1. Copy the directory import file for the site (the .csv file named for the site) to a Microsoft Exchange Server computer running the Administrator program.

2. Select the site you want to import users to.

3. From the Tools menu, choose Directory Import.

4. Select the import file you just copied.

5. Make sure the Create Windows NT account option is cleared.

6. Choose Import to begin the directory import process.

Note

If you perform more than one directory import, you should delete the Load Simulator container from your site before performing additional directory imports. Otherwise, properties for users that have already been imported will be merged with those of the import file.

Changing Default Permissions on User Accounts

Simulated users must be validated by a Windows NT domain when they connect to a Microsoft Exchange Server computer, just as if they were real users. Because Load Simulator simulates multiple users per Microsoft Exchange Client computer, you don't need a separate account for each user. Most load simulation tests require only a single account.

By default, Load Simulator grants mailbox owner permissions to every user account in the home server's domain. If the user account used by your Load Simulator client computers are in the same domain as your Microsoft Exchange Server computers, by default, all simulated clients can access the Microsoft Exchange Server computer.

If the default permissions are not sufficient, you can add additional account permissions in the directory import files that Load Simulator generates.

Editing user account permissions in a directory import file

1. After generating the directory import files, open the site import file (the .csv file named for the site) containing the user accounts for which you need to edit permissions.

2. Edit the list of account permissions that are separated by percent signs (%) at the end of each user import description line. The default value is \Domain Users.

For example, Jane has one simulated client in the Jane1 domain and another client and server in the Jane2 domain. The domains trust each other. After generating directory import files using Load Simulator, Jane uses a text editor to edit the site's .csv file. She edits the list of account permissions for each user so that when she imports the user accounts, the permissions will be set up correctly:

Jane1\Domain Users%Jane2\Domain Users.


Configuring Multiple Client Computers

If you need to run a large test with several hundred users or more, you may need multiple Load Simulator client computers. You can run Load Simulator on multiple clients by using the same .sim file on each.

A Load Simulator client can simulate users on multiple servers, but it can't span multiple sites simultaneously. To run a simulation involving multiple sites, you need at least one Load Simulator client computer per site. Users simulated in a test are divided among the clients defined for a given site based on the weights assigned to those clients. If all the weights are equal, an equal number of users are simulated on each of the clients.

You can assign clients with different weights to compensate for differences in client hardware capacities. For example, one of Jane's simulated clients (client_a) has 32 MB of RAM, the other (client_b) has 64 MB. Jane adds both clients to the list of clients that will be tested and assigns them different weights. She assigns client_a with a weight of 1 and client_b with a weight of 2. When Jane runs her tests, client_a will simulate one-third of the users in the test and the more powerful computer, client_b, will simulate the other two-thirds of the users.

Note

If you use multiple client computers, the clients must be able to access the message files. Copies of the message files should reside in the same directory on all of your client computers.

To set up multiple clients in your .sim file

1. From the Configuration menu, choose Client Machines.

2. Select the Use multiple client machines check box.

3. Select the clients that will be used in the test and their weighting values.

4. Save the .sim file and copy it to the same directory on each client's local disk.

Option | Description
Use multiple client machines | Indicates whether multiple client computers will be used in the test.
Test client machines | The client computers that will be used in the test.
Weighting | Specifies the weight value for client computer. The weight value is a relative number that indicates whether the selected client will be used more or less than other clients. For example, if client A has weight 1 and client B has weight 50, client B will be used 50 times more often than client A.
Client site | The site that contains the client computers.
Add Client(s) | Adds client computers to the list of clients that will be tested.
Remove | Removes a selected client computer from the list of clients that will be tested.


Setting the Type of Test

You can use Load Simulator to specify and run the following tests.

User Initialization

Creates folders and messages in the user mailboxes you specify, one or more at a time.

Public Folder Initialization (optional)

Sets up a public folder hierarchy in your site. This is required only if you have specified public folders in your topology.

Load Simulation

Simulates multiple users performing a wide variety of client actions. It is useful if you're using Load Simulator for capacity planning. The User Initialization and Public Folder Initialization tests are prerequisites for the Load Simulation test.

Configuring the User Initialization Test

When you set user initialization parameters, Load Simulator logs on to user mailboxes and adds items to the mailboxes to simulate real mailboxes. You can specify mailbox properties, including the type and number of messages in the mailbox and the number of messages in the Inbox. Your server's information store should be empty before you start the Initialize Users test.

You can perform the following user initialization tasks:

  • Specify the contents of mailboxes.
  • Select a subset of mailboxes to initialize.
  • Select a range of recipients to address messages to.
  • Select recipient options.

In most cases, the default user initialization values are sufficient for a standard Load Simulation test. You are required to set only the usage level in the Parameters property page.

Before you run the Load Simulation test, you should populate mailboxes with messages and folders. This helps to simulate a realistic usage scenario because mailboxes are not typically empty when users send and receive messages.

To specify the contents of mailboxes

1. From the Test menu, select User Initialization Parameters.

2. In the Parameters property page, specify the default settings for usage.

Option | Description
Number of processes per server | The number of processes that will be run per server. At least one process must be specified. For example, if you are initializing users on two servers and specify two processes per server, Load Simulator fills four mailboxes at a time until all mailboxes are populated.
Report status every message | Log statistics to the Load Simulator window. This option is typically not used.
Low usage | Specifies the number of new folders and messages you wish to create for each user mailbox. This usage definition corresponds with a low volume e-mail user.
Medium usage | Specifies the number of new folders and messages you wish to create for each user mailbox. This usage definition corresponds with a moderate volume e-mail user. This setting is used by default.
High usage | Specifies the number of new folders and messages you wish to create for each user mailbox. This usage definition corresponds with a high volume e-mail user.
Number of new folders | The number of new folders in mailboxes.
Number of messages per new folder | The number of messages in new folders.
Number of messages in Inbox | The number of messages in the Inbox.
Number of messages in Deleted Items | The number of messages in the Deleted Items folder.

If you want Load Simulator to test only some of the users you imported, you can select a subset of mailboxes for Load Simulator to initialize for the test. For example, you might select only some mailboxes if you're doing multiple tests that simulate different numbers of users.

To select a subset of mailboxes to initialize

1. From the Test menu, select User Initialization Parameters.

2. Select the Senders tab and specify the range of users' mailboxes that will be initialized.

Option | Description
Available Servers | Lists the servers in your simulated topology and the total number of users defined for each server.
Users Picked | Specifies a subset of the total number of users that are defined on a server. By default, all recipients are used.
Start at | The minimum number of users that will be used for the specified server. By default, this value is zero.
Count | The maximum number of users that will be used for the specified server. By default, this value is the total number of users or public folders defined for the server.
Add | Adds a server to the Available Servers list.
Add All | Adds all servers to the Available Servers list.
Remove | Removes a server from the Users Picked list.

If you want Load Simulator to use only some of the users you imported when addressing messages, you can select a range of recipients for your test.

To select a range of recipients that will be used to address messages

1. From the Test menu, select User Initialization Parameters.

2. Select the Recipients tab, and specify the range of recipients that will be used to address messages.

Option | Description
Available Servers | Lists the servers in your simulated topology and the total number of recipients defined for each server.
Users Picked | Specifies a subset of the total number of recipients that are defined on a server. The default is all recipients.
Start at | The minimum number of recipients that will be used for the specified server. The default is zero.
Count | The maximum number of recipients to be used by the specified server. The default is the total number of users or public folders defined for the server.
Add | Adds a server to the Available Servers list.
Add All | Adds all servers to the Available Servers list.
Remove | Removes a server from the Users Picked list.

You can select recipient options that will be used during your Load Simulation test such as the number of recipients that will receive a message. The options you select can help simulate a realistic usage scenario because how messages are sent and addressed can impact performance.

To select recipient options

1. From the Test menu, select User Initialization Parameters.

2. Select the Recipient Options tab, and specify the recipient options that will be used to address messages.

Option | Description
All available recipients | Each message will be addressed to the entire set of recipients specified in the Recipients property page. If this option is selected, local delivery options are ignored.
Use random recipients | Each message will be addressed to the specified number of recipients, which are selected randomly from those specified in the Recipients property page.
Between and average recipients | Specifies the minimum and maximum number of recipients for each message weighted to the average you select.
To local server | The percentage of messages sent to recipients on the same server as the sender. This option assumes you have specified multiple servers in the Recipients property page. For example, if you set the local server percentage to 90, only 10 percent of the mail will be sent to a recipient on another server.
To local site | The percentage of messages sent to recipients in the same site as the sender. This option assumes you have specified multiple sites in the Recipients property page. For example, if you set the local site percentage to 90, only 10 percent of the mail will be sent to a recipient in another site.
To local organization | The percentage of messages sent to recipients in the same organization as the sender. This option assumes you have specified multiple organizations in the Recipients property page. For example, if you set the local organization percentage to 90, only 10 percent of the mail will be sent to a recipient in another site.
Add distribution list to % of messages | The percentage of messages that are addressed to a distribution list if one is defined. This option should only be selected if you've imported distribution lists into the directory.

Note

The server, site, and organization traffic depends on a combination of the local delivery options selected and the composition of the distribution lists used, if any. If none of the local delivery options are selected, recipients are selected randomly from the entire set specified in the Recipients property page.

To simulate realistic usage scenarios, you can select the types and sizes of messages that are used to populate mailboxes. For example, you can select large or small messages with or without attachments. The messages you select should correspond to the type of usage level you're simulating.

To select messages used to populate mailboxes

1. From the Test menu, select User Initialization Parameters.

2. Select the Messages tab, and specify the recipient options that will be used to address messages.

Option | Description
List of .MSG files | The list of message files that Load Simulator will use in a test. By default, the list of messages corresponds to the usage definition you selected in the Parameters property page.
Weighting for selected file | Specifies the weight value for a message. The weight value is a relative number that indicates whether the selected message will be used more or less than other messages. For example, if message A has weight 1 and message B has weight 50, message B will be used 50 times more often than message A.
Add File(s) | Adds one or more .msg files.
Remove | Removes an .msg file.

Configuring the Public Folder Initialization Test

When you set public folder initialization parameters, Load Simulator initializes the public folders defined in your topology. To run this test, public folders and user initialization parameters must already be defined.

You can perform the following public folder initialization tasks:

  • Specify public folder initialization parameters.
  • Select the public folders that will be used.
  • Select messages that will be used to populate public folders.

If you want to test public folder usage in your test, you can populate public folders with messages before running the Load Simulation test. This helps to simulate a realistic usage scenario because public folders are not typically empty when they are used.

To set public folder initialization parameters

1. From the Test menu, select Public Folder Initialization Parameters.

2. In the Parameters property page, specify the distribution of messages per public folder.

Option | Description
Messages per folder | The minimum, maximum, and average number of messages in a public folder. For example, if you enter 1, 10, and 7 for the minimum, maximum, and average values, each public folder will have up to 10 messages with an average of 7 messages.
Show folder in address book | Each initialized folder is added to the global address list.
Use age limit (Expiry) | Messages will expire in the specified number of days.

If you're using public folders in your test, you should specify which public folders will be used during the test. This will help simulate a realistic usage scenario because some public folders are used more than others.

To select the public folders that will be used

1. From the Test menu, select Public Folder Initialization Parameters.

2. Select the Pick Public Folders tab, and specify the public folders that will be used on each server.

Option | Description
Available Servers | Lists the servers in your simulated topology and the total number of public folders defined for each server.
Folders Picked | Specifies a subset of the total number of public folders that are defined on a server. By default, all public folders are used.
Start at | The minimum number of public folders that will be used for the specified server. The default is zero.
Count | The maximum number of public folders that will be used for the specified server. The default is the total number of public folders defined for the server.
Add | Adds a server to the Available Servers list.
Add All | Adds all servers to the Available Servers list.
Remove | Removes a server from the Folders Picked list.

You should select the types and sizes of messages in the public folders that will be used during the test. This will help simulate a realistic usage scenario because the contents of public folders vary.

To select messages that will be used to populate public folders

1. From the Test menu, select Public Folder Initialization Parameters.

2. Select the Pub Fld Msgs tab, and specify the recipient options that will be used to address messages.

Option | Description
List of .MSG files | The list of message files that Load Simulator will use in a test. By default, the list of messages corresponds to the usage definition you selected for user initialization parameters.
Weighting for selected file | Specifies the weight value for a message. The weight value is a relative number that indicates whether the selected message will be used more or less than other messages. For example, if message A has weight 1 and message B has weight 50, message B will be used 50 times more often than message A.
Add File(s) | Adds one or more .msg files.
Remove | Removes an .msg file.

Configuring the Load Simulation Test

The Load Simulation test is key to testing a Microsoft Exchange Server computer. It is used to calculate server performance for a certain type of user. The user definitions are based on low, medium, and high usage of the Microsoft Exchange Client. You configure the Load Simulation test after you've populated user mailboxes with messages and any public folders.

In most cases, the default values are sufficient for a standard test. You are required to set only the usage level in the General property page.

Note

If you're using public folders, public folder initialization parameters must be defined before you configure public folders in the Load Simulation test.

To configure the Load Simulation test

1. From the Test menu, select Load Simulation Parameters.

2. If you are configuring a new Load Simulation test, select Yes to create a new test.

3. Type the name of the test.

4. In the General property page, specify the distribution of messages per public folder.

5. Specify any additional information and review your test's configuration using the Test Report property page.

This property page provides details about the load that will be generated on the server based on settings you've specified.

Option | Description
Test description | The name of the current test. The name you specified will be added to the .sim file.
New | Specify a new test.
Test duration | The amount of time the test will run. To manually stop the test, select Forever. To run multiple tests consecutively without pause, select Iterations. If Iterations is selected, length of day settings are ignored.
Low usage | Specifies default settings that correspond with a low volume e-mail user.
Medium usage | Specifies default settings that correspond with a moderate volume e-mail user. This setting is used by default.
High usage | Specifies default settings that correspond with a high volume e-mail user.
Read Mail | The simulated users will read mail during the test.
Send Mail | The simulated users will send mail during the test.
Schedule+ Actions | The simulated users will perform Microsoft Schedule+ tasks during the test.
Public Folders | The simulated users will use public folders during the test. This option should only be selected if public folders have been defined in your configuration.

Note

There is currently no mechanism for deleting or renaming a test.

When you run a test, it is important to consider how many hours in a day a user will use e-mail so you can simulate realistic usage patterns. The amount of e-mail traffic varies according to how frequently e-mail is used, which can affect your system's performance.

To set the length of a user's day

1. From the Test menu, select Load Simulation Parameters.

2. Select the Logoff tab and define the length of a user's day.

Option

Description

Daily schedule

The amount of time during the day or night that a user will use e-mail. This option can be used to increase the stress on the server. For example, if you want to double the amount of load on the server, shorten the user's day from 8 hours to 4 hours. This option does not affect the duration of the test.

Nighttime is specifies the length of the user's night. When a day is over, users log off (optional) and go to sleep for the specified period. Setting Nighttime is to zero disables the feature.

Log on immediately at beginning of the test

All users log on immediately at the beginning of the first day and never log off. No actions are begun until all the users are logged on.

Log off at the end of each day

All users log off at the end of each day.

Empty Deleted Items folder before logging off

The Deleted Items folder is emptied before users log off.

Log off after consecutive errors

After a certain number of consecutive errors, the user assumes that the server is unavailable and logs off. When the server is reactivated, the user automatically logs back on to perform the next scheduled action.

Log off when the next scheduled task is at least away

Users log off when the time between two tasks reaches the specified threshold. Don't select this option unless you're using Load Simulator to generate client performance data.

Because the frequency that users read and respond to mail can affect performance, your test should consider how users read their messages.

To set the properties for reading mail

1. From the Test menu, select Load Simulation Parameters.

2. Select the Read Mail tab, and define the properties used to simulate a user checking the Inbox and reading and responding to any new mail.

Option

Description

Read new mail times per day

The number of times per day users read new mail.

Read old mail times per day

The number of times per day users read old mail.

Read mail processing

The percentage of time that users reply, reply all, forward, move, copy, or delete messages. None is the percentage of messages that are read and then remain in the Inbox.

Load Simulator keeps track of how many times a particular message has been replied to (including reply all) or forwarded and reduces the percentage of reply, reply all, and forward actions accordingly. A message that has already been replied to or forwarded once is half as likely to be replied to or forwarded again.

Load % of attachments (on messages with attachments)

The percentage of message attachments that will be opened.

Limit Inbox to messages at any time

The number of messages allowed in a user's Inbox at the end of new mail processing. Any extra messages are moved to the Deleted Items folder.

Read note delay

The length of time a user pauses while reading a message. Load Simulator will use the specified minimum, average, and maximum values to randomly select a delay time when a user reads a message.

Important

When choosing percentage weighting values, you should use realistic values that approximate messaging in the real world. Setting certain percentage weighting values too high can create a message feedback loop that will overload your server and can invalidate your data.

You can select options for sending mail that will be used during your test such as how often users send messages and the destination of messages. The options you select can help simulate a realistic usage scenario because how messages are sent and addressed can impact performance.

To set the properties for sending mail

1. From the Test menu, select Load Simulation Parameters.

2. Select the Send Mail tab, and specify the number of messages each user will initiate a day and whether to save a copy of each sent message in the Sent Mail folder.

Option | Description
Send mail times per day | The number of times a day mail will be sent.
Save a copy in the Sent Mail folder | A copy of every message sent will be saved in the Sent Mail folder.
Select addressees from | Messages will be addressed to the specified recipients.
To distribution list | The percentage of messages that will be addressed to distribution lists.
To local server | The percentage of messages sent to recipients on the same server as the sender. For example, if you set the local server percentage to 90, only 10 percent of the mail will be sent to a recipient on another server.
To local site | The percentage of messages sent to recipients in the same site as the sender. For example, if you set the local site percentage to 90, only 10 percent of the mail will be sent to a recipient in another site.
To local organization | The percentage of messages sent to recipients in the same organization as the sender. For example, if you set the local organization percentage to 90, only 10 percent of the mail will be sent to a recipient in another site.
Msg. Priority | The percentage of sent messages that will be marked high, low, or normal priority.
Receipts | The percentage of messages that will generate delivery receipts, read receipts, both, or neither.

How users use Schedule+ can impact performance because heavier usage creates more load on the server. To simulate realistic usage scenarios in your test, you can select properties for using Schedule+.

To set the properties for using Schedule+

1. From the Test menu, select Load Simulation Parameters.

2. Select the Schedule+ tab, and define the properties that will be used to simulate a Schedule+ user.

Option | Description
Number of changes to schedule per day | The number of changes users will make to their schedule every day.
Update Free/Busy information | Specify whether to update free/busy information.
Schedule file size (in K) | The size of a user's schedule file.

If you're using public folders in your test, you should specify how public folders will be used during the test. This will help simulate a realistic usage scenario because public folder usage varies.

To set the properties for how public folders are used

1. From the Test menu, select Load Simulation Parameters.

2. Select the Public Folders tab, and select how public folders are used.

Option | Description
Number of times a day to open public folders | The number of times a day that public folders will be opened.
Percentage of time to open active folders | The percentage of time active public folders are opened. Active public folders are those that are used most frequently.
Read old item | The percentage of old items in public folders that will be read.
Read new item | The percentage of new items in public folders that will be read.
Change view | The percentage of times that the view on public folders will be changed.
Delete item | The percentage of items in public folders that will be deleted.
Post items | The percentage of items that will be posted to public folders.
Items to post | The number of items that will be posted to public folders.
Reply | The percentage of items posted to public folders that will be replies.
Reply to author | The percentage of items posted to public folders that will be reply to author.
Forward item | The percentage of items posted to public folders that will be forwarded.
Copy item | The percentage of items posted to public folders that will be copied.
Move item | The percentage of items posted to public folders that will be moved.
Modify item | The percentage of items posted to public folders that will be modified.
Percentage of time to do resolve-as-all | The percentage of time Load Simulator will resolve public folder conflicts by keeping all conflicting items. By default, Load Simulator resolves public folder conflicts by arbitrarily choosing a winner.


Running the Load Simulation Test

You can run your test once you've set up your test configuration and created your users.

To start or stop a Load Simulation test

  • From the Test menu, choose Run, and select the test you want to run.

-or-

  • From the Test menu, choose Stop.

You must wait for each client on the computer to finish processing.

You can also run the Load Simulator in unattended mode by typing the following at the command prompt.

LoadSim simfile testname /q

where simfile is the name of a .sim file that will be used and testname is the name of a test specified in the .sim file. If this is not specified, the .sim file is opened but the test is not run.


Customizing Load Simulator

You can customize Load Simulator environment options at any time, including the font used to display output in the Load Simulator window and the path to .msg files. You can also use Microsoft Exchange Client to create your own message files for tests.

To customize Load Simulator

1. From the Preferences menu, choose Options.

2. Specify the options.

Option | Description
Show time | Prepends the date and time to each line in the output window.
Show process ID | Prepends the identity of the client process to each line in the output window.
Show thread ID | Prepends the identity of the client thread to each line in the output window.
Output to file | All text in the output window is also written to the specified file.
Browse | Enables you to select an output file.
Overwrite previous file | Overwrites an existing output file if one exists.
Choose Font | Enables you to change the font displayed in the output window.
Message file path | The path to the message files.
Maximum simultaneous client logons | Allows you to control the number of Load Simulator processes that can log on simultaneously.

You can create your own message files to have more control over the size and types of messages you use in your test. For example, if your users typically send larger messages than the default messages provided with Load Simulator, you can create message files that more closely correspond with your scenario.

To create message files using Microsoft Exchange Client

1. In the Microsoft Exchange Client, create a new message or open an existing message.

2. Format the message as desired. It is not necessary to address the message because Load Simulator provides its own addresses.

3. From the message's File menu, choose Save As.

4. Under Save file as type, select Message Format, name your file, and choose OK.


Analyzing Load Simulator Data

As a performance tool, Load Simulator can help you answer the question: How many users per server does your Microsoft Exchange Server computer support? To determine the answer to this question, you can use Load Simulator to generate information about client response times. For more information about analyzing performance data, see the Microsoft Exchange Server white paper Performance: Concurrent Users Per Server that is available from the Microsoft Exchange Server web site (www.microsoft.com/exchange).

User Definitions

Usage patterns and activity levels depend on many factors, including business and personal use of messaging, scheduling, and workgroup capabilities, geographical distribution, and corporate culture. For example, a user can receive hundreds of messages each day or only one or two.

To standardize results and provide a basis for comparing results across topologies and platforms, Load Simulator defines three basic user types. These types are available in Load Simulator as preconfigured settings. You can also use Load Simulator to customize the default user definitions to match the usage patterns in your organization.

The following table contains the Load Simulator parameter definitions for the Initialize Users test. The Initialize Users test uses the same message file distribution and weighting as the Load Simulation test.

 | Usage definitions
Option | Light | Medium | Heavy
Number of new folders | 20 | 40 | 60
Number of messages per new folder | 5 | 5 | 5
Number of messages in Inbox | 1 | 4 | 9
Number of messages in Deleted Items | 1 | 1 | 1

The following table contains the Load Simulator parameter definitions that correspond with options in the Load Simulator test. The default message files that Load Simulator uses are provided for each applicable option.

 | Usage definitions
Option | Light | Medium | Heavy
Hours in day | 8 | 8 | 8
Send new mail (not reply or forward) | 2 times | 4 times | 6 times
Text only message |  |  |
1K text (Ups1k.msg) | 90 | 60 | 50
2K text (Ups2k.msg) |  | 16 | 10
4K text (Ups4k.msg) |  | 4 | 5
1K text message with attachment |  |  |
10K attachment (Ups10kat.msg) | 10 | 5 | 10
Excel attachment (UpsXLatt.msg) |  | 4 | 5
Word attachment (UpsWDatt.msg) |  | 2 | 5
Embedded bitmap (UpsBMobj.msg) |  | 2 | 5
Embedded Excel object (UpsXLobj.msg) |  | 2 | 10
Recipients per new or forwarded message | 3 | 3 | 3
Add distribution list to sent mail | 30% | 30% | 30%
Read new mail | 12 times | 12 times | 12 times
Reply | 5% | 7% | 15%
Reply All | 3% | 5% | 7%
Forward | 5% | 7% | 7%
Delete (move to Deleted Items folder) | 40% | 40% | 40%
Move | 20% | 20% | 20%
Load of attachments on read mail | 25% | 25% | 25%
Maximum Inbox size (in messages) | 20 | 125 | 250
Read old mail | 5 times | 15 times | 20 times
Number of changes to schedule per day | 1 | 5 | 10
Empty Deleted Items folder | 1 time | 1 time | 1 time
Messages sent per day (computed average) | 4.7 | 14.2 | 30.7
Messages received per day (computed average) | 22.9 | 66.3 | 118.9

Performance Log Parser

The Load Simulator includes a useful command-line tool called Load Simulator Performance Log parser (Lslog.exe) for manipulating data from performance log files. Lslog.exe accepts one command-line parameter and one or more Load Simulator performance log files and prints its results to a standard output device. You can use output redirection (< and >) to save or print the results. For information about using Lslog.exe, type lslog /? at the command prompt. Lslog.exe supports the following command-line parameters.

Option | Description
Truncate | Extracts a time window from a given log file and generates a new log file.
Merge | Combines two or more Load Simulator performance log files into one log file.
Answer | Generates nth percentile results for each type of action Load Simulator logs and a weighted average nth percentile result for all actions. By default, n is 95. The ninety-fifth percentile response time for a given action means that 95 percent of all response times recorded for that action were equal to or below that value.
Times | Lists the starting and ending time stamps for the given set of files. Time begins at 0.

Determining Users Per Server

To examine a server under load, you can run a simulated test and experiment with Performance Monitor on the server computer while the test is running. A more reliable and accurate method, however, is to generate a users per server (UPS) graph with data points from multiple load simulation tests. You can generate a UPS graph similar to the following graph produced by the Microsoft Exchange Server Performance Team.

To generate a UPS graph, you must run the test several times, once for each data point. To generate accurate data for a users per server (UPS) graph, it's important to follow the same steps correctly every time you run a test. Your results should also document any mistakes you make while running a test.

You can use the data in the log files that is generated after each test to produce a weighted average ninety-fifth percentile response time score that represents the capability of the servers to support the number of users in the tests. The ninety-fifth percentile response time for a given action means that 95 percent of all response times recorded for that action were equal to or below that value. This type of measurement is typical of many forms of statistical analysis. After graphing this score versus the number of users run and defining the limit of acceptable response times, you can determine an approximate number of users supported by the test system.

You can obtain additional information from the graph as well. The shape of the curve can tell you how well the server will support variable load. For example, if the curve is relatively linear, adding a few users won't make a significant difference in response times.

To generate a single data point for a UPS graph, you must first run the test for a certain number of users and then generate a score from the test data.

Generating Performance Data

The first step in generating a UPS graph is to generate a single data point for each test you run. You can gather additional data points by repeating the steps and increasing the number of users in each test.

The following are basic guidelines for generating a single data point on the UPS graph.

  • Verify that you're running the appropriate number of users for the current data point. For example, make sure that the message files and weights you defined in the Messages property pages match your user definitions.
  • If you're using multiple simulated clients, verify that they're all using the correct .sim file and have the same list of client computers. After you run the first test, you can verify that users are distributed correctly among the clients by checking the output log files for the names of the users that each client computer used.
  • The amount of physical RAM available on your Load Simulator client computers can affect the score. For accurate performance results, you should run no more than 100 simulated light or medium users on a 32 MB computer.
To generate data for a single data point

1. Run the load simulation test for a specific number of users.

If you have multiple clients defined, be sure to start them all.

2. Stop the test after an appropriate amount of time, which is typically eight hours. This time period depends on how long it takes the system to reach a steady state for the type of users you've defined. The data the Microsoft Exchange Server Performance Team generated was based on five-hour and six-hour test runs.

3. Archive the results. Gather additional data points by repeating these steps and increasing the number of users in each test.

Generating a Score from Performance Data

After you have generated data for a single data point, perform the following tasks to generate a score from raw Load Simulator performance log data. You must do this for each data point on the UPS graph.

1. Merge the log files from all of your simulated client computers using the LsLog merge command. This produces a single, combined performance log file for all simulated clients. You can also generate scores from a single control client and use the rest of the scores for verification of the control.

2. Extract the appropriate time window from the merged log file using the LsLog truncate command. For the data generated by the Microsoft Exchange Performance Team, the first two hours of data were removed from each six-hour test run.

3. Generate the ninety-fifth percentile response times and weighted average response time (the score) using the LsLog answer command.

For example, ClientA.log and ClientB.log are Load Simulator performance logs from a load simulation test that used two clients and ran for six hours. To generate the score, you would perform the following steps at the command prompt:

1. Type lslog merge ClientA.log ClientB.log > Merge.log

where ClientA.log and ClientB.log are log files generated on two client computers, and Merge.log is the merged log file.

2. Type lslog truncate Merge.log 2 6 > Truncate.log

where Merge.log is the merged log file, 2 6 is a four-hour window between the first and the fifth hours, and Truncate.log is the truncated log file.

3. Type lslog answer Truncate.log > Score.txt

where Truncate.log is the truncated log file and Score.txt is the file containing the score.


Chapter 9 Troubleshooting

Microsoft Exchange Server provides a variety of tools and diagnostics that can be used to troubleshoot problems in your organization. This chapter describes some of the problems you can encounter while using Microsoft Exchange Server. It is organized into the following sections:

  • Microsoft Exchange Server Setup
  • Directory
  • Microsoft Exchange Client Setup
  • Microsoft Exchange Client and Microsoft Schedule+
  • Performance
  • Internet Mail Connector


Microsoft Exchange Server Setup

If Setup indicates that it failed while installing Microsoft Exchange Server, in most cases you should reinstall Microsoft Exchange Server. If Setup fails but Microsoft Exchange Server seems to be working, there may be a problem with the network. After you've verified that the network connection is working correctly, complete the following steps to ensure that Microsoft Exchange Server is correctly installed.

1. Turn off all Microsoft Exchange Server services.

2. Restart the server.

3. Run the Setup program and reinstall any components that Setup did not successfully install during the initial installation.

If Setup fails while you're adding a new server to a site, information about the new server may have been replicated to other servers in the site. To prevent the site's directory from becoming corrupted if directory replication has already been initiated, you may need to remove the new server from the site's directory before reinstalling the server. Complete the following steps to ensure that Microsoft Exchange Server is installed correctly in the site.

1. In the Administrator program on the remote server you specified during Setup, delete the Server object for the new server.

2. Run Setup again on the new server, and choose Remove All.

3. Run Setup again on the new server, and reinstall Microsoft Exchange Server.


Public Folders

When you establish a new site, public folder replication cannot occur until the directory has been replicated. If the directory replication interval is long, the information store may try to replicate public folders before the new site has been added to the directory. To ensure that public folders replicate successfully, you can wait for the directory to replicate the new site information or force directory replication to occur. You can do this by choosing Update Now in the General property page for the server directory.

Note

If you force directory replication to occur, choose a time when the server's performance is not critical and connection costs are low.


Directory

You can have the following problems with the directory if:

  • Addresses aren't displaying in the correct language.
  • Objects in a site can't be modified.


Addresses Aren't Displaying in the Correct Language

If the global address list doesn't display addresses in the correct language, you may not have installed the correct language display template in the directory. For information about installing language display templates, see Chapter 3, "Working with Microsoft Exchange Server."


Directory Objects Can't Be Modified

You may not be able to modify directory objects in a site for the following reasons:

  • The objects are read-only.
  • You are logged on under an account that doesn't have permission to modify that object.

To change properties on an object, verify that you have permission to modify it. Keep in mind that some objects can reference objects in another site, so you may also need permission to modify those objects.


Microsoft Exchange Client Setup

If you have problems installing Microsoft Exchange Client, ensure the following are true:

  • The user and server names are correct.
  • The directory is running on the Microsoft Exchange Server that the Microsoft Exchange Client is connecting to.
  • If Windows for Workgroups is installed, the patch available on the Windows NT 3.51 compact disc is installed as described in the Microsoft Exchange Server Installation Guide.


Microsoft Exchange Client and Microsoft Schedule+

This section contains troubleshooting information and tips for the Microsoft Exchange Client and Schedule+.


Messages Remain in the Outbox

The following are reasons messages remain in the Outbox for more than a few seconds:

  • The message is incorrectly addressed.
  • The information service used to send this message is unavailable.
  • The Microsoft Exchange Server is unavailable.
  • The user is working offline.


Unread Message Count Is Incorrect

If the unread message count on a personal folder file (.pst) or an offline folder file (.ost) is incorrect, you can run the Scanpst tool included with the Microsoft BackOffice Resource Kit: Part One. You should run this tool if the user's unread message count is off by one or more messages.


Offline Synchronization Stops Responding

When using an offline folder file (.ost), the Microsoft Exchange Client can stop responding during startup if offline synchronization doesn't complete successfully. You can disable offline synchronization by editing the user's messaging profile as described in the following steps:

1. From the Tools Menu, choose Services.

2. Under The following information services are set up in this profile, select Microsoft Exchange Server.

3. Choose Properties.

4. Select the Advanced tab, and then choose Offline Folder File Settings.

5. Choose Disable Offline Use.

Note

If the problem persists, you may also need to rename the .ost file.


Resource Won't Automatically Book Meeting Requests

If a resource such as a conference room does not automatically book meeting requests, the resource may have been put in the Required or Optional boxes instead of the Resource box. Entering resources in any address box other than the Resource box disables this feature in Schedule+.

Note

Automatically booking appointments does not work when meeting requests are sent between Microsoft Mail for PC Networks postoffices and Microsoft Exchange Server.

To ensure that resources can be booked automatically:

  • Inform users to put conference rooms in the Resource list box when requesting meetings.
  • Place the resource account in the Resource box of the Select Attendees dialog box so the resource is included in the Bcc box of the Meeting Request form and displayed in the Where box of the meeting request message. Schedule+ searches only for users listed in the Bcc box to automatically book appointments.


Password Can't Be Changed When Using Novell VLM Client Software

When you try to change the password on a Microsoft Exchange Client computer that is running Novell VLM client software, the following error can occur.

The NT Domain password could not be changed. A required action was not successful due to an unspecified error.

Solution

  • Install Gateway Services for NetWare on the primary domain controller (PDC) where the user accounts are located.
  • Ensure the Novell client is running the latest Novell connectivity files.
  • Ensure the remote procedure call (RPC) service is configured to start automatically. This can be changed by choosing Services in the Control Panel.
  • Ensure the registry on the PDC has the following entries:

    HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\LSA

If the PDC has NWLINK installed, add the following entry to the registry:

NetWareClientSupport:REG_DWORD:0x1

If the PDC has TCP/IP installed, add the following entry to the registry:

TcpipClientSupport:REG_DWORD:0x1
  • Ensure the PDC is running the same version of Windows NT Server as the Microsoft Exchange Server, including all service packs.


Performance

Windows NT Performance Monitor can be used to help you troubleshoot performance problems that affect Microsoft Exchange Server. It provides information about performance statistics such as processor use, memory use, server throughput, queue size, and number of write/read operations per second. You can use the preconfigured Performance Monitor chart views that are included with Microsoft Exchange Server to help you improve your system's performance and identify bottlenecks.

The following are the most typical indications of performance bottlenecks.

  • Microsoft Exchange Client or Microsoft Exchange Server is slow.
  • Mail delivery is slow.

For information about the Performance Monitor chart views for Microsoft Exchange Server, see Appendix C, "Performance Monitor Chart Views."


Microsoft Exchange Client Is Slow

If Microsoft Exchange Client takes longer than usual to start up or seems slow, you can improve performance by doing the following:

  • Modify the RPC binding order on the Microsoft Exchange Client computer so the protocol that the client uses to connect to the Microsoft Exchange Server computer is the first listed in the RPC binding order. For more information about modifying the RPC binding order, see Chapter 2, "Setup."
  • If the Microsoft Exchange Client is using multiple information services, create different messaging profiles so services are loaded only when needed. For example, it can take longer to start up Microsoft Exchange Client if Internet services and MSNä, the Microsoft online service, are also loaded.
  • Upgrade the Microsoft Exchange Client computer by adding more RAM or disk s pace, increasing the speed of the CPU, or adding a high performance network adapter and driver.


Microsoft Exchange Server Is Slow

If the Microsoft Exchange Server computer appears to be slower than normal, one or more of the following conditions probably exist:

  • CPU activity is high.
  • Disk activity is high.
  • Memory (RAM) usage is high.

To isolate the problem to one of these areas, ask the following questions:

  • Is the server supporting other applications?
  • Is the server handling too many users?
  • Has the user activity changed? Are users sending more mail than usual, sending mail with large attachments, or sending to large distribution lists?

The following sections describe how to isolate the problem further.

CPU Activity Is High

To determine whether the CPU is overworked, run the Performance Monitor Server Health chart view. If the CPU is the problem, your chart will be similar to the following illustration.

You can further isolate the problem by running the Performance Monitor Users chart view. If the Users Count counter is high, the server may be supporting more users than it's capable of supporting.

Solutions

Complete the following to improve CPU use:

  • Restrict the amount or type of mail users can send.
  • Move Microsoft Exchange Server components or other applications to another server.
  • Move some or all mailboxes and public folder replicas to another server.
  • Add a faster processor.
  • If your server is a symmetric multiprocessor (SMP), add additional processors.
  • Optimize the way the system responds to foreground and background applications. In Control Panel, choose System, choose Tasking, and then select Foreground and Background Applications Equally Responsive.
  • Upgrade to a CPU that has more Level 2 (L2) caching, particularly if the server has less than 256K of L2 cache. Some systems allow up to 2 megabytes (MB) or more of L2 memory. L2 cache is faster than RAM.

Disk Activity Is High

Run the Performance Monitor Server Health chart view to determine whether the disk is overworked. If the disk is causing the problem, the chart will be similar to the illustration on the following page.

Note

If you haven't done so already, you should start the disk performance counters by typing diskperf -y at the command prompt. Then, add the LogicalDisk: Disk Bytes/sec and LogicalDisk: % Disk Time counters to the Microsoft Exchange Server Health chart view. These counters indicate the amount of data that is transferred to or from the disk during write or read operations. For more information about adding counters to charts, see your Windows NT Server documentation.

Look at the disk and pages/sec. counters to determine which disk is the problem. If paging is high, the disk containing the pagefile is causing the problem.

Solutions

Complete the following to improve disk use:

  • Move Microsoft Exchange Server transaction logs to another physical disk or another physical disk that is using a different disk controller than the disk containing the databases.
  • Restrict the amount or type of mail users can send.
  • Add more RAM and run Performance Optimizer to increase the database buffers.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.

Memory Usage Is High

Run the Performance Monitor Server Health chart view to determine whether the server is running out of memory. If RAM is causing the bottleneck, the pages/sec counter will be high (typically greater than 100 pages per second), and the chart will be similar to the following illustration.

Solutions

Complete the following to improve memory use:

  • Add more RAM.
  • Increase the size of your pagefile. In Control Panel, choose System, and then choose Virtual Memory. Under Paging File Size For Selected Drive, set a large pagefile. You can approximate the pagefile size by adding 125 MB to the amount of physical RAM available on your server. For example, if your server has 64 MB of RAM, you should set your pagefile size to 189 MB.
  • Move the pagefile to a separate physical disk.
  • Ensure Windows NT Server is optimized for network applications. In Control Panel, choose Network, choose Server in the list of installed network software, choose Configure, and then select Maximize Throughput for Network Applications.
  • Restrict the amount or type of mail users can send.
  • Move Microsoft Exchange Server components or other applications to another server.
  • If your server is paging excessively, adjust the size of the database buffer caches by typing perfwiz -v at the command prompt. You should reduce the size of the buffer cache by 10 to 30 percent.
  • Move some or all mailboxes and public folder replicas to another server.


Mail Delivery Is Slow

If the Microsoft Exchange Server computer appears to be delivering mail more slowly than normal, one or more of the following can be backlogged:

  • The message transfer agent (MTA) queue.
  • The information store (public or private) queue.
  • The Internet Mail Connector queue.

Ask the following questions to isolate the problem.

  • Is the server handling too many users?
  • Has the user activity changed? Are users sending more mail than usual, sending mail with large attachments, or sending to large distribution lists?

The following sections describe how to isolate the problem further.

MTA Queue Is Backlogged

Run the Performance Monitor Server Queues chart view to determine whether the MTA queue is the bottleneck. This shows how much traffic the MTA is transmitting to and from other servers, sites, or organizations. If the MTA is causing the mail to be delayed, the Work Queue Length counter will be high and the chart will be similar to the following illustration.

If the MTA queue is backlogged and there is high disk activity, the disk containing the databases is causing the problem. The queue can be backlogged because the MTA can't write to disk quickly enough.

Solutions

Complete the following to improve the speed of message processing in the MTA queue:

  • Restrict the amount or type of mail users can send.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.

Private Information Store Queue Is Backlogged

Run the Performance Monitor Server Queues chart view to determine whether the private information store queue is the bottleneck. This shows how many messages the private information store is delivering to mailboxes. If the private information store is causing the mail to be delayed, your chart will look like the following illustration.

Solutions

Complete the following to improve the speed of message processing in the private information store queue:

  • Restrict the amount or type of mail users can send. For example, require users to send mail to public folders instead of distribution lists.
  • Move some or all mailboxes to another server.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.

Public Information Store Queue Is Backlogged

Run the Performance Monitor chart view Server Queues to determine whether the public information store queue is the bottleneck. This shows how many messages the public information store is delivering to public folders. For example, if it is taking longer than usual for public folder changes to be replicated throughout your system, the following counters will show increased activity:

  • MSExchangeIS Public: Send Queue Size
  • MSExchangeIS Public: Receive Queue Size
Solutions

Complete the following to improve the speed of message processing in the public information store queue:

  • Configure public folder replication to occur at another time or less frequently.
  • Move some or all public folders to another server.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.

Internet Mail Connector Queue Is Backlogged

Run the following Performance Monitor chart views: Server IMC Traffic, Server IMC Statistics, and Server IMC Queues to determine whether the public information store queue is causing the problem. These chart views show how much traffic the Internet Mail Connector is transmitting to and from the Internet. For more information about troubleshooting the Internet Mail Connector, see "Internet Mail Connector" on the following page.

Solutions

Complete the following to improve the Internet Mail Connector processing speed:

  • Restrict the amount or type of mail users can send to the Internet.
  • Move the Internet Mail Connector to another server.
  • Add more disks to the stripe set.
  • Use multiple disk controllers.
  • Add one or more caching disk controllers that cache read and write operations.


Internet Mail Connector

This section describes how to solve the following problems with the Internet Mail Connector:

  • Unable to send or receive Internet mail.
  • The Internet Mail Connector service will not start.


Unable to Send or Receive Internet Mail

This section describes how to troubleshoot the following problems:

  • Outbound Internet mail sits in the queue or is returned to the sender as Host Unknown.
  • Inbound Internet mail arrives at the domain name server and sits in the queue.
  • Mail sent from the Internet addressed to users in the organization is returned as Host Unknown or Recipient not Recognized.

Solutions

To successfully send and receive Internet Mail, check the following:

  • Verify the Microsoft Exchange Server site address.
  • Verify the Windows NT TCP/IP settings.
  • Verify that Domain Name Service (DNS) is configured correctly.
  • Verify the Internet Mail Connector address space is valid.
  • Use the DNS Resolver to verify your configuration.
Verifying the Site Address

The default Microsoft Exchange Server simple mail transport protocol (SMTP) domain name is based on the organization and site name specified during installation. For example, Ferguson and Bardell's organization name (FAB) and site name (NAmerica-SW) are used to generate the following domain name.

namerica-sw.fab.com

The domain name is appended to the mailbox name to generate an SMTP address for messages sent through the Internet Mail Connector. For example, a user named Fran Wilson sending an SMTP message from this site has the following SMTP address.

franwilson@namerica-sw.fab.com

It is important to verify that the SMTP address for the site is the same address you specified in DNS or the hosts file. To check the SMTP site address, complete the following steps:

1. In the Administrator window, choose Configuration.

2. Double-click Site Addressing.

3. Select the Site Addressing tab.

4. If the SMTP site address is incorrect, edit it.

Make a note of the site address for later use.

For more information about site addresses, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server Administrator's Guide.

Verifying the Windows NT TCP/IP DNS Settings

Whenever possible, the TCP/IP DNS host and domain names should match the Microsoft Exchange Server organization and site names. Check the Windows NT TCP/IP configuration by completing the following steps:

1. In Control Panel, choose the Network icon.

2. In the Installed Network Software box, select TCP/IP Protocol, and then choose Configure.

3. Choose DNS.

4. Verify that the DNS Host Name is the Microsoft Exchange Server site name and the DNS Domain Name is the Microsoft Exchange Server organization name. If you use a host and domain name that is different from the site and organization name, be sure that your domain name server has a mail exchanger (MX) record.

For more information about organization and site names, see the Microsoft Exchange Server Concepts and Planning Guide and the Microsoft Exchange Server Administrator's Guide. For more information about Windows NT TCP/IP, see the Windows NT Server documentation.

Verifying the DNS Configuration

If you do not maintain a DNS server in your organization, you will need to work with your Internet provider to ensure the correct DNS records are specified for your organization. It is important to understand how address (A) records and MX records are used to verify their accuracy.

Internet mail and DNS settings are similar to letters and the postal system. The post office delivers a letter based on the street name and street number specified on the envelope. Internet mail is delivered through a query to DNS based on the domain name specified for the recipient. An A record is like the street address, and an MX record is the street number.

The A record should match the domain name in the Windows TCP/IP configuration. If the site name does not equal the host name specified in DNS, you need an MX record. For more information, see the Microsoft Exchange Server Administrator's Guide.

In the example, the TCP/IP host name is tucson03 and the domain name is fab.com. The SMTP site address is @NAmerica-SW.fab.com. It is likely that a message will be sent user@fab.com rather than user@NAmerica-SW.fab.com, so an MX record is needed to correlate NAmerica-SW (the house number) with fab.com (the street name). To ensure the message is delivered, the A record and MX record look like the following.

Tucson03.fab.com.    IN A 10.31.67.198
NAmericaSW.fab.com IN MX 10 Tucson03.fab.com.

For more information about DNS, see the Microsoft Exchange Server Concepts and Planning Guide, the Microsoft Exchange Server Administrator's Guide, and your DNS server documentation.

Verifying the Address Space

The address space of a connector creates a path for messages. It identifies the recipient type and addresses that the message passes through. If the address space is not defined, messages will not pass through it. If the address space is incorrect, some messages may not pass through it. Verify the address space for the Internet Mail Connector by completing the following steps:

1. In the Administrator window, choose Connections.

2. Double-click Internet Mail Connector.

3. Select the Address Space tab.

In this case, the address space is configured to process all SMTP type addresses (*.*). If the address space is not defined, create a new one. If it is not defined correctly, edit it.

For more information about address spaces, see the Microsoft Exchange Server Administrator's Guide.

Using the Internet Mail Connector DNS Resolver Test

The Internet Mail Connector DNS Resolver Test performs a DNS query for MX records that match the specified domain. A list is created of one or more IP addresses in the same order of preference the Internet Mail Connector uses in its attempt to deliver mail for that domain.

If the MX query returns no results, a query for the A record matching the domain is performed. The result is a single IP address. If the A record search returns no results, the host file on the local computer is checked. If a match is found, the result is a single IP address.

The DNS Resolver Test is useful for checking DNS or host file configurations and for troubleshooting delivery problems.

Run the Internet Mail Connector DNS Resolver Test from the Support\Utils directory on the Microsoft Exchange Server compact disc. Run the test from the same computer that runs the Internet Mail Connector after TCP/IP and DNS are configured.

To run the IMC DNS Resolver Test with options, type the following at the command prompt.

restest [-debug] domain

Using -debug causes additional information to be displayed at each step of the search.


Internet Mail Connector Service Will Not Start

When the Internet Mail Connector service will not start, ensure the host name and domain name have been specified in the Windows NT TCP/IP configuration.


General Problems

The following problems can occur:

  • Event id 2168 occurs when starting the Internet Mail Connector.
  • The Microsoft Mail Connector stops delivering mail.
  • Messages delivered to a distribution list fail because the recipient not recognized message occurs.

Solutions

These problems occur when the X.400 address is deleted on an object, such as a mailbox, connector, or distribution list. Try re-creating the address.

The Microsoft Exchange Server MTA is a native X.400 MTA. Therefore, X.400 addresses exist for every object. In a native X.400 system, it is important to have the X.400 address available for each object at all times. The Microsoft Exchange Server MTA can route and deliver on the distinguished name (DN) but requires that an X.400 address exist if there are problems with the DN. Microsoft Exchange Server also uses the X.400 address information to make routing decisions to foreign systems. In this case, the X.400 address and the foreign address information is used to route the message within the Microsoft Exchange Server topology.


Appendix A Creating an .Ini File for MS Exchange Server Batch Setup

This appendix describes the format for creating an .ini file that you can run with Microsoft Exchange Server Setup in batch mode (Setup /q). Using an .ini file is equivalent to selecting options in dialog boxes during Setup; however, the .ini file provides additional options, so you have more control over your installation. For more information about batch Setup, see Chapter 2, "Setup."


.Ini File Format

Each section of the .ini file follows with the setting, a description, and the value. The .ini file settings are not case-sensitive.


[Paths]

This section contains entries that specify the location where optional components will be installed. All entries are optional.

Entry | Description | Value
ServerDest= | Where the server component will be installed if selected. | Server name
AdminDest= | Where the Administrator program will be installed if selected. | Path


[Components]

This section contains entries that specify which components will be installed. All entries are optional.

Entry | Description | Value
Services= | Whether to install the services for the system attendant, the directory, the information store, and the message transfer agent (MTA). | True or false
Administrator= | Whether to install the Administrator program. | True or false
MSMailConnector= | Whether to install the Microsoft Mail Connector. | True or false
Internet= | Whether to install the Internet Mail Connector. | True or false
X400= | Whether to install the X.400 Connector. | True or false
Sample Applications= | Whether to install the sample applications that clients can use. | True or false
Books Online= | Whether to install online documentation. | True or false


[Site]

This section contains entries that specify the names of directory objects in the site, such as the site and server names.

Entry | Description | Value
ExistingServerName= | Name of the server in the existing site. | Server name
SiteName= | Name of the new site if ExistingServerName is not provided. | Site name
SiteProxyName= | Proxy name of the new site. Used to determine the site addresses for connectors. | Site proxy name
InternetSiteName= | Internet site name if the Internet Mail Connector is being installed. | Internet site name (for example, Litware.com)


[Organization]

This section contains entries that specify the names of directory objects in the organization.

Entry | Description | Value
OrganizationName= | Organization name if a new site is being created. | Organization name
OrganizationProxyName= | Organization proxy name if a new site is being created. Used to determine the site addresses for connectors. | Organization proxy name


[ServiceAccount]

This section contains entries that specify the service account name and password.

Entry | Description | Value
AccountName= | Service account name. This entry is required if a new site is being created. | Service account name
AccountPassword= | Service account password. This entry is required. | Service account password


[Licensing]

This section contains entries that specify licensing information.

Entry | Description | Value
PerSeat= | Whether to set up licensing on a per-seat basis. | True or false
PerServer= | Whether to set up licensing on a per-server basis. | True or false
PerServerUsers= | Number of users licensed on this server. Required if PerServer= is used. | Number of users

Note

The following is required in the [Licensing] section if the Services setting in the [Components] section is set to true:

  • Either PerSeat= or PerServer= must be true.
  • If PerServer= is true, PerServerUsers= must be specified.


[SitePermissions]

This section contains entries that specify the user account(s) that will have Administrator permission in the site.

Entry | Description | Value
Account1= Account2= Account3= Account4= | Account that will be granted site Administrator permission. Up to four accounts can be specified. These accounts are in addition to the service account specified in the [ServiceAccount] section. | User account (for example, Namerica\mariab)


[X.400]

This section configures X.400 support and is optional. For more information about these entries, see your X.400 documentation.

Entry | Description | Value
Organization= | X.400 attribute for organization | X.400 O
OrgUnit1= | X.400 attribute for organizational unit | X.400 OU1
OrgUnit2= | X.400 attribute for organizational unit | X.400 OU2
OrgUnit3= | X.400 attribute for organizational unit | X.400 OU3
OrgUnit4= | X.400 attribute for organizational unit | X.400 OU4
PrivManDomName= | X.400 attribute for the private management domain (PRMD) | X.400 PRMD
AdminManDomName= | X.400 attribute for the administrative management domain (ADMD) | X.400 ADMD
Country= | X.400 attribute for country | X.400 C


Appendix B System Management Checklist

You should regularly check the following items on your Microsoft Exchange Server. The list is divided into daily, weekly, monthly, and periodic maintenance tasks.

For more information, see the Microsoft Exchange Server Administrator's Guide and the Microsoft Exchange Server Concepts and Planning Guide.


Daily

  • Examine Windows NT Performance Monitor counters.
  • Monitor services and links.
  • Back up your data.
  • Purge unneeded transaction log files. Monitor the Edb*.log files in the Dsadata and Mdbdata directories for the build up of transaction log files.

Warning

Do not manually delete the edb*.log files. To remove these files, perform a full or incremental backup or turn circular logging on.

  • Check available disk space.
  • Check the Alerter service.


Weekly

  • Check event logs for errors and warnings.
  • Check for message tracking log file buildup.
  • Verify that public folders are being replicated.


Monthly

  • Validate information store backups by restoring them to an alternate server that is not part of your organization.


Periodically

  • Run information store maintenance. Check the IS Maintenance property page on the Server object in the directory to ensure that the maintenance routines run during off-peak hours and at least once per day.
  • Defragment the server offline. Take the server offline and use the defragmentation utility (Edbutil.exe) to defragment the directory and information store.
  • Check mailbox and public folder use as follows:
    • Check the Logons property pages in the private and public information stores.
    • Check the Mailbox Resources and Public Folder Resources property pages to see how individual users and public folders are using storage space.
  • Check storage limits. Monitor storage limit settings on mailboxes and public folders. You may need to adjust these limits periodically for certain users or public folders.


Appendix C Performance Monitor Chart Views

Microsoft Exchange Server provides several Windows NT Performance Monitor chart views with preselected counters that you can use to troubleshoot performance problems. You will typically use more than one chart view at a time to isolate a performance problem. The following chart views are available in the Microsoft Exchange program group.

Performance Monitor chart | Description
Microsoft Exchange Server Health | Tracks the server's memory use in pages per second and the amount of processor time used for each server core component.
Microsoft Exchange Server Load | Tracks the amount of load on the server resulting from client requests and replication operations.
Microsoft Exchange Server History | Tracks statistics such as the number of messages the server processes and the pages per second generated since the server was started.
Microsoft Exchange Server Users | Tracks the number of users who are accessing the server's information store.
Microsoft Exchange Server Queues | Tracks the amount of time for the server to respond to client requests. Also tracks the speed of replication operations.
Microsoft Exchange Server IMC Traffic | Tracks the amount of traffic that the server's Internet Mail Connector processes.
Microsoft Exchange Server IMC Statistics | Tracks the number of inbound and outbound messages that the server's Internet Mail Connector processes.
Microsoft Exchange Server IMC Queues | Tracks the number of inbound and outbound messages that the server's Internet Mail Connector sends to the Internet or Microsoft Exchange Server.

Note

If you haven't done so already, start the disk performance counters by typing diskperf -y at the command prompt. Then, add the LogicalDisk: Disk Bytes/sec and LogicalDisk: % Disk Time counters to the Microsoft Exchange Server Health chart view. These counters indicate the amount of data that is transferred to or from the disk during write or read operations. For more information about adding counters to charts, see your Windows NT Server documentation.


Server Health Chart View

The following counters are available in the Microsoft Exchange Server Health chart view.

Counter | Object | Instance | Description
% Total Processor Time | System |  | The amount of time that the processor is busy.
% Processor Time | Process | Directory | The amount of time that a processor is busy servicing directory requests.
% Processor Time | Process | MTA | The amount of time that a processor is busy servicing message transfer agent (MTA) requests.
% Processor Time | Process | Information store | The amount of time that a processor is busy servicing information store requests.
% Processor Time | Process | System attendant | The amount of time that a processor is busy servicing system attendant requests.
Pages/sec | Memory |  | The number of memory pages that are read from or written to the system's pagefile on disk.


Server Load Chart View

The following counters are available in the Microsoft Exchange Server Load chart view.

Counter | Object | Description
Message Recipients Delivered/min | Private information store | The rate at which messages are delivered to mailboxes.
Messages Submitted/min | Private information store | The rate at which users send messages.
Message Recipients Delivered/min | Public information store | The rate at which messages are delivered to public folders.
Message Submitted/min | Public information store | The rate at which users send messages to public folders.
Adjacent MTA Associations | MTA | The number of connections this MTA has to other MTAs.
RPC Packets/sec | Information store | The rate at which remote procedure call (RPC) packets are processed.
AB Browses/sec | Directory | The rate at which users browse the Address Book.
AB Reads/sec | Directory | The rate at which users perform read operations on the Address Book.
ExDS Reads/sec | Directory | The rate at which Extended Directory Service clients (the information store, MTA, system attendant, and Administrator program) perform read operations on the directory.
Replication Updates/sec | Directory | The rate of directory replication activity on this server.


Server History Chart View

The following counters are available in the Microsoft Exchange Server History chart view.

Counter | Object | Description
Total Message Recipients Delivered | Private information store | The total number of recipients who have received a message since the server was started.
Total Messages Delivered | Private information store | The total number of messages delivered to recipients since the server was started.
Total Messages Sent | Private information store | The total number of messages the MTA sent to store providers since the server was started.
Total Messages Submitted | Private information store | The total number of messages that users sent since the server was started.
Total Message Recipients Delivered | Public information store | The total number of recipients who have received a message since the server was started.
Total Messages Sent | Public information store | The total number of messages the MTA sent to information services since the server was started.
User Count | Information store | The total number of users who are connected to the information store.
Work Queue Length | MTA | The total number of messages the MTA has not yet processed.
Pages/sec | Memory | The total number of memory pages that are read from or written to the system's pagefile on disk.


Server Users Chart View

The following counters are available in the Microsoft Exchange Server Users chart view.

Counter | Object | Description
User Count | Information store | The number of users who are connected to the information store.


Server Queues Chart View

The following counters are available in the Microsoft Exchange Server Queues chart view.

Counter | Object | Description
Work Queue Length | MTA | The number of messages that the MTA has not yet processed.
Send Queue Size | Private information store and public information store | The number of sent messages that are waiting for final delivery.
Receive Queue Size | Private information store and public information store | The number of received messages that are waiting for final delivery.


Server IMC Traffic Chart View

The following counters are available in the Microsoft Exchange Server IMC Traffic chart view.

Note

The Internet Mail Connector must be running to use these counters.

Counter | Object | Description
Messages Entering MTS-IN | Internet Mail Connector | The number of messages received from the Internet that are waiting for final delivery to Microsoft Exchange Server.
Messages Entering MTS-OUT | Internet Mail Connector | The number of messages being sent to the Internet that are waiting to be converted to Internet mail format.
Messages Leaving MTS-OUT | Internet Mail Connector | The number of messages that are waiting for final delivery to the Internet.
Connections Inbound | Internet Mail Connector | The number of current simple mail transport protocol (SMTP) connections to the Internet Mail Connector established by other SMTP hosts.
Connections Outbound | Internet Mail Connector | The number of current SMTP connections that the Internet Mail Connector has established to other SMTP hosts.


Server IMC Statistics Chart View

The following counters are available in the Microsoft Exchange Server IMC Statistics chart view.

Note

The Internet Mail Connector must be running to use these counters.

Counter | Object | Description
Inbound Messages Total | Internet Mail Connector | The total number of Internet messages the Internet Mail Connector receives.
Outbound Messages Total | Internet Mail Connector | The total number of messages the Internet Mail Connector sends.


Server IMC Queues Chart View

The following counters are available in the Microsoft Exchange Server IMC Queues chart view.

Note

The Internet Mail Connector must be running to use these counters.

Counter | Object | Description
Queued Inbound | Internet Mail Connector | The number of messages received from the Internet that are waiting to be converted for Microsoft Exchange Server.
Queued MTS-IN | Internet Mail Connector | The number of messages received from the Internet that are waiting for final delivery to Microsoft Exchange Server.
Queued MTS-OUT | Internet Mail Connector | The number of messages that are waiting to be converted to Internet mail format.
Queued Outbound | Internet Mail Connector | The number of messages that are waiting to be delivered to the Internet.


Appendix D Setting Permissions

Organizations that make information available to a diverse audience need to manage who can access that information. Some individuals and groups need more access to information and resources than others. You can control who can use Microsoft Exchange Server resources by granting and restricting access to directory objects, public folders, and mailbox folders. For example, you can set permissions for directory objects and public folders or delegate access to mailboxes so that users can send e-mail on behalf of other users. You can use these features to enhance the security in your organization or as a convenience to your users.


Setting Permissions on Resources

Microsoft Exchange Server permissions give you a high degree of control over the amount of access people have to resources such as directory objects and public folders. The permissions you set depend on your organization's security requirements. For example, if you're the only person administering Microsoft Exchange Server, you can set permissions only on the most critical resources so that no one else can have access to them. If your organization has a large Management Information Services (MIS) department, you can assign administrators different levels of permissions to control who can access resources. You can grant administrators with the most authority permission to access the entire directory, while granting other administrators only the authority to create mailboxes. For more information about setting permissions, see your Microsoft Exchange Server documentation.


Directory Permissions

You can control access to objects in the directory by using the Administrator program to assign roles to Windows NT Server user accounts and groups. Roles are sets of permissions that are provided for administrative convenience. They define how much and what type of access a user or group has to an object. For example, the Administrator role gives administrators a number of permissions that help them perform their daily tasks. You can define custom roles or use the following default roles provided with Microsoft Exchange Server:

  • Admin.
  • Permissions Admin.
  • Service Account Admin.
  • View Only Admin.
  • User
  • Send As

Each role is defined by a set of permissions that defines the specific actions that a particular user account or group can perform on an object. For example, the Delete permission grants the ability to delete an object. The following table describes the permissions.

Permission | Description
Add Child | Creates objects below the selected object in the directory hierarchy. For example, if a user has this permission for the Recipients container, that user can create mailboxes in that container.
Modify User Attributes | Modifies user-level attributes associated with an object. For example, a user with this permission can modify the members of a distribution list.
Modify Admin Attributes | Modifies administrator-level attributes associated with an object. For example, a user with this permission can modify the job title and display name fields in a mailbox.
Modify Permission | Modifies permissions on existing objects. For example, without this permission, a user could grant permissions for new mailboxes but could not modify permissions for existing ones.
Delete | Deletes objects.
Send As | Sends messages with the sender's return address. For example, all users have this permission for their mailbox so that they can send messages with that mailbox's return address. This permission is also granted for server objects in the directory to the service account so that directory service processes can send messages to each other.
Mailbox Owner | Reads and deletes messages in this mailbox. This permission is also granted for server objects in the directory to the service account, so that directory processes can send messages to each other.
Logon Rights | Accesses the directory. Users need this permission to use the Administrator program. Services also need this permission.
Replication | Replicates directory information with other servers. This permission is required by the Microsoft Exchange Server service account to replicate with other servers.

You can grant permissions to groups of users, as well as to individual user accounts. Permissions are also used by Microsoft Exchange Server services. Most permissions apply only to the Administrator program; however, some permissions, such as Modify User Attribute, can apply to the Microsoft Exchange Client.

Roles are associated with the following permissions.

Role
Permission | Admin. | Permissions Admin. | Service Account Admin. | View Only Admin. | User | Send As
Add Child | X | X | X |  |  |
Modify User Attribute | X | X | X |  | X |
Modify Admin Attributes | X | X | X |  |  |
Delete | X | X | X |  |  |
Logon | X | X | X | X |  |
Modify Permission |  | X | X |  |  |
Replication |  |  | X |  |  |
Mailbox Owner |  |  | X |  | X |
Send As |  |  | X |  | X | X


Folder Permissions

You can set permissions for public folders and mailbox folders by assigning a role to a user name that appears in the global address list. You can define custom roles or use the following default roles:

  • Owner
  • Publishing Editor
  • Editor
  • Publishing Author
  • Author
  • Reviewer
  • Contributor
  • None

Every folder has a default user that grants permissions to undefined users. To give only defined users permission to use a public folder or mailbox folder, you can set the default user to None.

Each role is defined by a set of permissions as follows.

Permission | Description
Create Items | Grants the user permission to post items in the folder.
Read Items | Grants the user permission to open any item in the folder.
Create Subfolder | Grants the user permission to create subfolders in the folder.
Folder Owner | Grants all permissions in the folder.
Folder Contact | Grants the user Folder Contact permission. Folder Contacts receive automated notifications from the folder, such as replication conflict messages and requests from users for additional permissions or other changes in the folder.
Edit Items | None: Prevents the user from editing any item. Own: Grants the user permission to edit the user's own items. All: Grants the user permission to edit any item.
Delete Items | None: Prevents the user from deleting any item. Own: Grants the user permission to delete the user's own items. All: Grants the user permission to delete any item.

Roles are associated with the following permissions.

Role
Owner | Publishing Editor | Editor | Publishing Author | Author | Reviewer | Contributor | None
X | X | X | X | X |  | X |
X | X | X | X | X | X |  |
X | X |  | X |  |  |  |
X |  |  |  |  |  |  |
X |  |  |  |  |  |  |
All | All | All | Own | Own | None | None |
All | All | All | Own | Own | None | None |


Setting Permissions for Servers

Administrators need special permissions to administer Microsoft Exchange Server. For example, certain permissions are required to perform typical tasks on a Microsoft Exchange Server computer, including installing Microsoft Exchange Server and backing up and restoring data.


Installing Microsoft Exchange Server

You must have the following permissions to install Microsoft Exchange Server.

  • To run server Setup, the user account you're logged on as must be a member of the Windows NT Server Administrators local group.
  • To join an existing site during Setup, the user account you're logged on as must be assigned the Permissions Administrator role on the site's Organization, Site, and Configuration objects.


Performing Administrative Tasks

You must have the following permissions to perform typical tasks with the Administrator program.

  • To create a new recipient, your user account must be assigned the Permissions Administrator role for the Site object. No additional permissions are necessary. To create a new user account, your user account must be a member of the Windows NT Server Administrators global group in the domain that you are adding the account to.
  • To modify properties on objects other than permissions, your user account must be assigned the Permissions Administrator role on the object, or it must inherit this role from another object.
  • To modify permissions on objects, your user account must be assigned the Permissions Administrator role on the object or it must inherit this role from another object.
  • To view properties on objects without modifying them, your user account must be assigned the View Only Administrator role on the object, or it must inherit this role from another object.


Backing Up and Restoring Data

You must have the following permissions to back up and restore data. These permissions are set in User Manager.

  • To back up data, you must be a member of the Windows NT Server Backup Operators group on each server that is backed up. Only administrators can add users to this group.
  • To restore data from tape backup, you must be a member of the Windows NT Server Administrators group on each server being restored. Only administrators can add users to this group.


Setting Permissions for Clients

In many corporate environments, users often need to have access to other users' mailboxes, schedules, and public folders. For example, a manager can give an assistant permission to send e-mail on behalf of the manager. Users can also grant other access to their mailboxes and schedules.


Setting Up a Delegate User on a Mailbox

You can assign another user to act as a delegate for a user's mailbox or Microsoft Schedule+. A delegate can perform various activities using someone else's mailbox or schedule depending on the permissions the mailbox owner grants to the delegate. The procedures in this section describe how to grant a user Delegate permissions for someone else's mailbox and open another user's mailbox as a delegate.

To grant a user Delegate permissions for a mailbox

1. Log on to the Microsoft Exchange Client as the mailbox owner.

2. In the folder list, select the mailbox or a mailbox folder.

3. From the File menu, choose Properties, and then select the Permissions tab.

4. To add a name to the Name/Role list, choose Add.

5. Under Type Name Or Select From List, type or select the name, choose Add, and then choose OK.

6. In the Name/Role list, select the name of the user to whom you want to grant permissions.

7. Under Permissions, select a predefined role in the Roles box, or select the individual permissions.

You must grant a minimum of Read Items (Reviewer role) permission to allow another user to open the mailbox.

Choose OK.

To open another user's mailbox as a delegate

1. From the Tools menu in the Microsoft Exchange Client, choose Services.

2. In The Following Information Services Are Set Up In This Profile box, select Microsoft Exchange Server, and then choose Properties.

3. Select the Advanced tab, and then choose Add.

4. In the Add Mailbox box, type the name of the additional mailbox you have permission to access.

5. Choose OK until all open dialog boxes are closed.

Note

When a delegate opens the mailbox, the delegate can open only the folders the user has granted permission for.


Setting Up a Mailbox to Send on Behalf of Another Mailbox

Send on Behalf of permissions enable a user to send messages with the user's name after "Sent On Behalf Of" and the delegate's name after "From." These permissions can be set up using either Microsoft Exchange Client or the Administrator program. You can use the Administrator program to grant Send on Behalf of permissions if the mailbox owner is not available.

To grant Send on Behalf of permissions by using Microsoft Exchange Client

1. From the Tools menu in the Microsoft Exchange Client, choose Options, and then select the Exchange Server tab.

2. Choose Add.

3. Under Type Name or Select from List, type or select the user's name.

4. Choose Add, and then choose OK.

To grant Send on Behalf of permissions by using the Administrator program

1. In the Administrator window, choose Recipients, and then select the name of the recipient you want to configure.

2. From the File menu, choose Properties, and then select the Delivery Options tab.

3. Under Give Send On Behalf Of permissions to, choose Modify.

4. In the Address Book, select the recipient and then choose Add.


Setting Up a Mailbox to Send As Another Mailbox

If a user has Send As permissions on a mailbox, that user can send a message with that mailbox's return address so that it appears that the message was sent by the mailbox's owner. Send As permissions can be granted to user accounts only with the Administrator program.

Note

Send As permissions override Send on Behalf of permissions. For example, if a user has both Send As and Send On Behalf of permissions for another user, any message sent in the other user's name will have that user's name as the return address.

To grant Send As permissions

1. In the Administrator window, choose Recipients, and then select the name of the recipient you want to configure.

2. From the File menu, choose Properties, and then select the Permissions tab.

If the Permissions tab is not available, choose Options from the Tools menu, select the Permissions tab, and then select the Show Permissions page for all objects and Display rights for roles on Permissions page check boxes.

2. Select the user account that you're granting permissions to, or choose Add to add an additional account.

3. Under Roles, select Send As, and then choose OK.


Setting Permissions on a Schedule

By default, all users can access the free and busy times for other users. However, a user must have permission to open another user's appointment book or view details of another user's busy times. Users can grant permissions to other users to access their appointments, contacts, events, or tasks. Schedule+ items marked as Private can't be accessed unless a user is an owner or delegate owner on the item.

To set up access to a user's schedule

1. From the Tools menu in Schedule+, choose Set Access Permissions.

2. Choose Add, double-click the delegate, and then choose OK.

3. In the User role box, select a role, and then choose OK.

To view another user's schedule

1. From the File menu in Schedule+, choose Open, and then choose Other's Appointment Book.

2. Select a user name and then choose OK.


Setting Permissions on Public Folders

This section describes how to set up a public folder owner or contact and how to set permissions on public folders.

Setting Up a Public Folder Owner or Contact

A public folder's owner and contact have special permissions on the public folder. A public folder owner can design public folders and grant other users permissions. A public folder contact receives notification when there are public folder conflicts or the contents of a public folder exceed the storage limit. Only a public folder owner or an administrator using the Administrator program can make someone a public folder owner or contact.

To set up a public folder owner or contact

1. In Microsoft Exchange Client, select the public folder.

2. From the File menu, choose Properties, and then select the Permissions tab.

3. Choose Add, double-click the name of the user that you're granting permissions to, and then choose OK.

4. Select the name of the user you added.

5. In the Roles box, select Folder Owner or Folder Contact, and then choose OK.

Granting Permissions on Public Folders

You can use the Administrator program to grant users permissions for public folders or enable them to create top-level folders. If you're the owner of a public folder, you can also use Microsoft Exchange Client to grant other users permissions to create subfolders.

To grant permissions for public folders using the Administrator program

1. In the Administrator window, choose Public Folders, and select the public folder you want to configure.

2. From the File menu, choose Properties, and then select the General tab.

3. Choose Client Permissions.

4. Choose Add, double-click the user that you're granting permissions to, and then choose OK.

5. Choose the user you added.

6. Select Folder owner or Folder contact, and then choose OK.

To grant permissions to create top-level folders by using the Administrator program

1. In the Administrator window, select Configuration, double-click Information Store Site Configuration, and then select the Top Level Folder Creation tab.

2. Choose Modify to change the list of users who can create top-level folders.

3. Double-click the user that you're granting permissions to, and then choose OK.

4. Choose OK.

To grant permissions to create subfolders by using Microsoft Exchange Client

1. In Microsoft Exchange Client, select the public folder.

2. From the File menu, choose Properties, and then select the Permissions tab.

3. Choose Add, double-click the user that you're granting permissions to, and then choose OK.


Appendix E Tools

Microsoft Exchange Server provides a variety of tools that can be used to troubleshoot problems in your organization. These tools are in the Tools directory on the Microsoft BackOffice Resource Kit: Part One compact disc. The following tools are described in this appendix. Additional tools are available on the compact disc.

Name | Directory | Description
Mailbox Cleanup Agent | Cleanup | Configures different age limits on mailbox folders.
Microsoft Exchange Server Preview Pane Extension | Cliext | Adds a third area for previewing the body of messages in the Microsoft Exchange Client.
Event Log Tools | Eventlog | Monitors and filters events and sends alerts when specified events occur.
Import Header Tool | Headers | Creates import or export templates for the objects selected from the directory.
IMC Configuration Restorer | Imccopy | Exports specific Internet Mail Connector configuration information into a file so that it can be imported to another Internet Mail Connector.
IMC Sample Extension DLL | Imcext | Intercepts inbound messages from simple mail transport protocol (SMTP) hosts and selectively reroutes those messages to other SMTP hosts before they are processed by the Internet Mail Connector.
IMC Configuration Extractor | Imcsave | Extracts Internet Mail Connector messages and configurations from the Microsoft Exchange Server information store and directory. These messages and configurations are then restored on another computer.
Microsoft Exchange Address Export to MS Mail | Msmailex/Eximwiz | Converts Microsoft Exchange Bulk Export format (.csv) to MS Mail import format.
RPC Counter | Rpc | Measures remote procedure call (RPC) traffic between the client and the server.
Bulk Advanced Security Tool | Security | Encrypts and decrypts messages.
Command Line Mail Sender | Sendmail | Sends mail messages and file attachments from the command line.
Mailbox Statistics | Storstat | Collects statistics about e-mail usage.
MS Mail SMTP Gateway Proxy Migration | Msmailex/Migsmtp | Preserves current Internet addresses of the recipients and adds them as secondary proxies to the Microsoft Exchange address list, eliminating the need for end users to republish their new Internet address for their business associates.
MS Mail Proxy to Microsoft Exchange Proxy Conversion | Msmailex/Proxy | Converts existing SMTP/MHS/X.400 addresses from MS Mail Export format to Microsoft Exchange Bulk Import format (.csv) to be added as custom recipients to a Microsoft Exchange recipient container


Mailbox Cleanup Agent

You can use the Mailbox Cleanup Agent to control client use of disk space on Microsoft Exchange Server computers. The Mailbox Cleanup Agent gives administrators more flexibility to delete and move outdated messages in users' mailboxes.

The Mailbox Cleanup Agent consists of a Windows NT Server service, a configuration object in the Microsoft Exchange Server directory, and a mailbox agent. Configuration information is contained in the Mailbox Cleanup Agent directory object in the Add Ins container. The mailbox agent originates the status reports that are sent to users after their mailbox has been cleaned. One instance of the Mailbox Cleanup Agent controls an entire site.


Installing the Mailbox Cleanup Agent

1. In the Tools\Cleanup directory on the Microsoft BackOffice Resource Kit: Part One compact disc, double-click Setup.exe.

2. Provide the following information:

  • The Microsoft Exchange Server computer where the Mailbox Cleanup Agent will reside. This can be any server in the site.
  • The site name.
  • The container where the Mailbox Cleanup Agent will be located. You can place it in any recipient container in the site (for example, the Recipients container).
  • The service account and service account password. This account is the security context the agent runs under. It can be any account, but it's a good idea to use the service account that you are using for the Microsoft Exchange Server services.
  • The service directory specifying where the Mailbox Cleanup Agent will be installed. The path to this directory must include a drive letter.

3. In the Microsoft Exchange Server Administrator program, find the Mailbox Cleanup Agent in the container you specified in the previous step and open its property pages. Configure the containers and schedule pages.

4. After Setup is completed, start the Mailbox Cleanup Agent service using Services in Control Panel.

Note

If you start the service before configuring the agent's property pages, the service stops and logs an event indicating that it has not been configured.


Using the Mailbox Cleanup Agent

You can configure the Mailbox Cleanup Agent to move messages based on age limits. Within each recipient container in a site, age limits can be set on the user's Inbox, Sent Items folder, Deleted Items folder, and all other folders as a group. Outdated messages can be moved to the Deleted Items folder or to a special private folder so users can process the messages at their own discretion. After the Mailbox Cleanup Agent has cleaned out a mailbox, it sends a message to the user describing the cleanup operations that were performed. The tool also logs information for administrators to the Windows NT Server Event Log.

To enforce when deleted items are permanently deleted, the tool can be set to delete items from the Deleted Items folder. To allow your users to control which messages are deleted, you can configure the Mailbox Cleanup Agent to move messages to the System Cleanup folder. If the System Cleanup folder doesn't already exist when cleanup is run, the Mailbox Cleanup Agent creates it. The System Cleanup folder is a private folder in the user's mailbox that can remind users to delete outdated messages. It does not actually delete the messages; users can keep messages moved to the System Cleanup folder by dragging and dropping them into a personal folder file (.pst file).

The System Cleanup folder contains subfolders for each folder that is cleaned. For example, if you configure the Mailbox Cleanup Agent to move messages in Sue's mailbox to the System Cleanup folder, the folder hierarchy might look as follows:

Inbox

Sent Items

Sue's Folder

System Cleanup folder

Inbox

Sent Items

Sue's Folder

Setting General Configuration Options

1. In the Administrator window, choose Recipients.

2. Double-click the mailbox agent for the Mailbox Cleanup Agent.

3. Select the Containers tab.

4. In the left side of the Containers property page, select the container for the mailboxes you want to clean. The settings for the selected container are displayed on the right side of the property page.

5. Specify the age limits on folders and where outdated messages will be moved.

Option | Description
Use parent's configuration | The selected container is cleaned using the same settings as the parent container. This option is available on child containers only. It is enabled by default. When this option is selected, other options in the property page are disabled, except for Exclude mailboxes.
Folder | The folders containing the messages you want to move or delete. You can set age limits for messages in the Inbox, the Sent Items folder, and all other folders as a group.
Age limit (days) | The limit on how old messages can be before they are moved during the scheduled operation of the Mailbox Cleanup Agent.
Move to folder | Qualifying messages are moved to either the Deleted Items folder or the System Cleanup folder.
Permanently delete items in the Deleted Items folder older than (days) | The limit on how old messages in the Deleted Items folder can be before they are permanently deleted during the scheduled operation of the Mailbox Cleanup Agent. If an age limit is not specified, deletion depends on the user's default configuration. If a number of days is specified, messages are permanently deleted if their receive date is older than date the tool is run minus the specified number of days. If you want to postpone deletion of messages that are moved during the same session, set the age limit to a number greater than the age limit for the other folders.
Max number of items to move per mailbox | The number of messages that are moved before the Mailbox Cleanup Agent stops cleaning one mailbox and begins processing another. Deleted items are deleted only after those in all other folders have been processed. So, if the limit of items processed in other folders is reached before those in the Deleted Items folder are processed, then the items in the Deleted Items folder are not deleted. The default is 50.
Exclude mailboxes | Excludes specified mailboxes in the container from the cleanup session.

You can set up the Mailbox Cleanup Agent to run unattended on many mailboxes throughout a site according to the schedule you specify.

Setting the Cleanup Schedule

1. In the Administrator window, choose Recipients.

2. Double-click the mailbox agent for the Mailbox Cleanup Agent.

3. Select the Schedule tab.

4. Specify the cleanup frequency to daily, weekly, or monthly.


Microsoft Exchange Server Preview Pane Extension

Microsoft Windows 95 and Windows NT Workstation users can use the Microsoft Exchange Server Preview Pane Extension to add a third area for previewing the body of messages to the Microsoft Exchange Client Viewer. The contents of the To and Subject boxes can also be displayed in the preview pane message header, but no attachments or other boxes are available for preview. Users can set reminders on messages or folders. In addition, a user can determine the size of a folder and its subfolders.

Users can also use Preview Pane Extension to mark messages as read, set reminders on messages or folders, automatically synchronize offline folders on a specified schedule, view messages in a fixed font, and move or copy messages or folders in the Microsoft Exchange Client hierarchy.

A user customizes Preview Pane Extension using the Preview tab in the Options dialog box available from the Microsoft Exchange Client Tools menu. The extension dynamic-link library (DLL) for these options resides on the user's workstation.

Preview Pane Extension may appeal to more experienced users in your organization because it combines some of the functionality of Microsoft Schedule+ type reminder features with Microsoft Exchange Client folders and messages. However, new users will also find it easy to customize and use Preview Pane Extension.

Preview Pane Extension uses approximately 1 megabyte (MB) of space on the share where you make it available to users. Preview Pane Extension is a Microsoft Exchange Client extension that uses MAPI and supports users with Microsoft 32-bit operating systems. Preview Pane Extension supports advanced security through the Microsoft Exchange Advanced Securities Extensibility application programming interface (API). It also supports uniform resource locators (URL). When a user reads an Internet address text in the preview pane, the text can be used as an operational Internet link if the address text is valid.

When an extension is added to Microsoft Exchange, another module is loaded, which can impact overall performance. The preview pane generates an RPC for each item stored on a server that is previewed by a user. Also, each window resize can cause additional RPCs. A user may notice this when using Remote Access Service (RAS).

A Preview Pane Uninstall icon is included in the Microsoft Exchange program group when a user sets up Preview Pane Extension. Running the uninstall program removes all Preview Pane Extension files. However, if it fails to remove these files, you can delete the registry entries.

Preview Pane Extension stores its configuration data in HKEY_Local_Machine\Software\Microsoft\Exchange\Client\Extensions by adding the following value:

4.0;c:\Windows\tripane\tripane.DLL;1;11010010000000;1101010.

You can disable Preview Pane Extension by removing the value.

It's a good idea to distribute Preview Pane Extension to a small group of users to test before making it available for wide release. A minimum of 30 days is recommended as a test period. Based on this experience, you can modify the documentation you send to users.


Installing Preview Pane Extension

To make Preview Pane Extension available to users, you need to copy it from the Microsoft BackOffice Resource Kit: Part One compact disc to a network share, then install it on a client computer running Windows NT Workstation or Windows 95.

To install Preview Pane Extension to a network share

1. Locate the Tools\Cliext directory on the Microsoft BackOffice Resource Kit: Part One compact disc.

2. Copy its contents to the server share where you want users to find it.

To install Preview Pane Extension on a Client Computer

1. Connect to the network location where Preview Pane Extension is available for setup.

2. Double-click Setup.exe.


Using Preview Pane Extension

You can use Preview Pane Extension with Microsoft Exchange Server if you are running either the Windows 95 or Windows NT Workstation operating system. You can use it to preview the body text of messages (together with the To and Subject information), to set reminders on messages or folders, or to determine the size of a folder.

You can customize Preview Pane Extension as follows:

  • Set reminders on messages or folders.
  • Hide or display the preview pane message header.
  • Mark messages as read, either at the end of a time period, such as 5 seconds, or when you click off the message.
  • Use a filter to display only unread messages in the preview pane.
  • Synchronize offline folders automatically on a schedule.
  • Customize the client toolbar with Preview Pane Extension buttons.
  • Display messages with a fixed font.

To customize the Preview Pane Extension

1. From the Microsoft Exchange Client Tools menu, choose Options, and select the Preview tab.

2. Select the options you want, and then choose OK.

3. From the Microsoft Exchange Client Tools menu, choose Customize Toolbar, and then add the Preview Pane Extension buttons you want to use.

To display the preview pane

· From the View menu, select Preview.

To hide the preview pane

· From the View menu, clear Preview.

Note

If you installed the Show/Hide Preview Pane button on your Microsoft Exchange Client toolbar, you can select it instead of choosing the Preview command.

To set a reminder on a message or folder

1. In the Microsoft Exchange Client, select a folder or message.

2. From the File menu, choose Reminder.

3. In the Preview Pane Reminder dialog box, select the options you want, and then choose Save.

Note

If you installed the Reminder button on your Microsoft Exchange Client toolbar, you can click it instead of choosing the Preview Pane Reminder command.

When you move a message or folder that has a reminder, you lose the reminder. Reminders you set are private because reminder information is stored only on your local computer.

To copy or move a folder or message

1. From the Tools menu, choose Options, and then select the Preview tab.

2. Set up a Copy or Move button.

3. From the Tools menu, choose Customize Toolbar, and then display the corresponding tool on the toolbar.

4. In the Viewer, select a message.

5. On the Microsoft Exchange Client toolbar, click the Copy or Move button.

To determine folder size

1. In the Viewer, select a folder.

2. From the File menu, choose Folder Size.

To view a message using a fixed font

1. Right-click the text in the preview pane.

2. From the shortcut menu, choose Fixed Font.

Preview Pane Extension Shortcut Menu

When you use the preview pane, you can find commands for that message on its shortcut menu.

To open a shortcut menu

· In the preview pane, right-click a message. Depending on the message, the following commands are available.

Command | Description
Open | Opens the message in normal mode so that you can identify and work with attachments.
Remind | Opens the Preview Pane Reminder dialog box, where you can set a reminder for the message.
Previous | Displays the previous message.
Next | Displays the next message.
Copy | Copies selected text to the Clipboard.
Select All | Selects all text in the message body.
Find | Opens the Find dialog box.
Fixed Font | Displays the message body in a monospace font.
Stop Reading | Stops the mark-as-read countdown timer. When you choose this command, the message will not be marked as read. You can also press the ESC key to stop the timer.

Options Dialog Box and Preview Tab Options Settings

Show Message Header in Preview Pane

Select this option to hide or display the preview message header. The preview pane message header displays the contents of the To and Subject boxes of a message.

Mark Messages as Read in Preview Pane

Select this option to mark messages as read. When this option is selected, you can modify the time period or defer marking messages. The default is 5 seconds. To adjust the time period, select the number in the Wait box and then type a new number.

Defer Marking Until Selection Changes

Select this option to mark messages as read only when you click off the message. This option is available only when the Mark Message as Read option is selected. You can use the two marking options together. If you don't want messages you read using the preview pane to be marked as read, clear Mark Message as Read in the preview pane. If you want to be certain you've read a message before it's marked, select both Mark Message as Read and Defer Marking Until Selection Changes.

Synchronize Every <variable> Minutes After Full Idle

Select this option to synchronize your folders with their offline counterparts every <variable> number of minutes. To adjust the time period, select the option, select the number displayed in the box, and then type a new number.

Before you can set a synchronization default time period using Preview Pane Extension, you must create at least one offline folder.

Process Secure Messages

Select this option to process secure messages in the preview pane. Secure messages have been encoded using the Microsoft Exchange Client Encrypt Message Contents and Attachments feature.

Reminder Administrator

Select this option to open the Preview Pane Reminder Viewer, where you can review your reminders.

Copy/Move Buttons Box

Select these options to copy or move a message to a folder. You can also specify an action to automatically follow any copy or move, such as opening the item below it, returning to Microsoft Exchange Server, or doing nothing. Choose New or Modify to open the Button Properties dialog box, and then select the options you want. Choose Delete to delete a button.

Before any options you set in the Copy/Move Buttons box are available, you must customize your Microsoft Exchange Client toolbar by choosing the Customize Toolbar command on the Tools menu. Preview Pane Extension buttons are in the Customize Toolbar dialog box. After they have been added to the toolbar, ToolTips are available.

Message Reminder Viewer Dialog Box Options

Use this dialog box to view reminders you've set. You can select a way to view them (either View Reminders as They Expire, View All Message Reminders, View All Folder Reminders, View Message Reminders By Date, or View Folder Reminders By Date) by choosing a new filter.

When you choose View All Message or All Folder Reminders, double-click an item to read it. When you choose View All Messages or All Folder Reminders By Date, you can change the date from its default (the default is the current date).

When you work in the Reminder Viewer, you can use the following buttons:

Button | Description
Close | Closes the Reminder Viewer.
Open | Opens a message if a message reminder is selected
Properties | Opens the Set Reminder dialog box, where you can revise a reminder
Disable | Maintains reminder information but doesn't display a reminder
Snooze | Delays the reminder according to the time you add using the Snooze dialog box.
Select All | Selects all messages and folders.
Delete | Deletes the selected reminders. Use the Delete button with care; there is no Undo to recreate reminders that you delete.

Right-click on a message or folder in the Reminder Viewer to open a shortcut menu that displays the commands you can use with that message or folder.

Message Reminder Dialog Box Options

Disabled

Select to disable, but not lose, reminder information you set in the When and Occurs boxes. In the upper-right corner, check the information to verify you've selected the number of messages or folders you want to set a reminder on.

When Box

Use this area to set up the reminder.

Remind at

You can type a time, such as 12:00 P.M., or set the time and date by using any one or all of the Time Remaining boxes.

On

Click the > button to open the calendar if you want to change the day displayed in the On box. When you open the calendar, double-click the date you want. Use the buttons in the upper-right and upper-left corners of the calendar to move back or forward one month per click.

Time Remaining

You can use the Days, Hours, Minutes, and Seconds boxes to set a reminder. Otherwise, the boxes display the time remaining before the reminder appears.

Occurs

Use the features available in this area to set a recurring reminder for one of the following intervals: every 15 or 30 minutes, hourly, daily, weekly, monthly, yearly, or by the weekday. Select By Weekday to enable the days of the week check boxes. The default recurring reminder is None. Choose Save to save your reminder. Choose Viewer to open the Message Reminder Viewer.

.Dat Files

Two files, Reminder.dat and Buttons.dat, contain the dynamic data that is written when a user uses Preview Pane Extension. Buttons.dat contains all the button settings and customized options for a user; Reminder.dat contains all the reminders.


Event Log Tools

You can use the Event Log tools to:

  • Monitor events on more than one server.
  • Filter events based on service, type, and ID.
  • Alert a computer or user through e-mail when specified events occur.


Installing Event Log Tools

Install the files from Tools\Eventlog into a directory on a computer that is running the services you want to monitor. To have Evtscan alert you through e-mail, you must install it on a computer that has MAPI installed (for example, a Microsoft Exchange Server or Microsoft Exchange Client computer).


Monitoring Events

Use the Event Log Filter tool (Elf.exe) to specify the servers and events that you want to monitor. After you specify what you want to monitor, the tool writes the results to a text file. It can monitor events on servers, or it can filter events saved in .evt files by using the Windows NT Server Event Viewer.

Note

You can save an event log filter using the Configuration Add and Remove buttons.

To monitor events

1. Run Elf.exe.

2. Choose Add and Remove to specify the servers and .evt files you want to monitor.

3. Specify the name of the output text file.

4. Specify how far back you want to check events.

5. Select the services you want to monitor.

Choose Advanced to specify individual event IDs to ignore for a service.

6. Specify the entry types you want to monitor.

7. Select the Unattended box if you want to skip over errors and continue.

8. Choose Go to start the filter.

The output text file created is in the same format as the Windows NT Server Event Viewer, except that it monitors more than one server and it adds the text description for events.

Displaying Event Log Output in Microsoft Access

If you have Microsoft Access, you can use the Microsoft Access Elf.mdb file to provide common summaries of the events. To do so:

1. Start Microsoft Access.

2. Open Elf.mdb.

3. Choose Open Event Log and specify the full path to the output file created with the Event Log Filter.

4. Choose View Details.

The top half of the view window shows the count of each event ID found. Click an event to see individual occurrences in the bottom half of the window.

Note

The Elf.mdb database will grow with use. You need to compact this database manually by using the Tools.Database Utilities.Compact Database option in Microsoft Access.

Monitoring for Specific Events

You can use the Event Log Scan tool (Evtscan.exe) to monitor servers for specific events. When a specified event is detected, the Event Log Scan tool can be configured to:

  • Send a message.
  • Send a network pop-up to specific computers.
  • Restart or stop the service.
To configure the Event Log Scan tool

1. Create a configuration file with a .cfg extension specifying the events and actions required. The format is as follows:

EventID;Source;Action;Alert list;Mail list;Comment string

Configuration Entry | Description
Event ID | The numerical event ID (see the Windows NT Server Event Viewer).
Source | The source name for the service to monitor.
Action | The action to take; can be Restart or Stop.
Alert list | A comma-separated list of computers to send network pop-ups to when the event is detected.
Mail list | A comma-separated list of e-mail aliases to notify when the event is detected.
Comment string | A comment that is included in the alert pop-up and e-mail message when the event occurs.

2. Run Evtscan.exe by using the following command-line format:

evtscan -f config_file -t delay_in_seconds server_list

where config_file is the name of the configuration file created in step 1, delay_in_seconds is the time the tool waits between scans (for example, typing -t 15 means the tool scans for events every 15 seconds), and server_list is a comma-separated list of the servers to monitor for the events.

3. Leave Evtscan.exe running on the desktop. You might want to minimize the command prompt window.

Sample Configuration File

The following is a sample configuration file:

;sample config file.
9277;MSExchangeMTA;restart;nobellchem;nobellchem;Event 9277
9278;MSExchangeMTA;stop;nobellchem;;Event 9278
9279;MSExchangeMTA;;nobellchem;nobellchem;Event 9279
9297;MSExchangeMTA;restart;nobellchem;nobellchem;Event 9297


Import Header Tool

The Import Header tool creates header text files for importing and exporting a variety of directory objects, such as mailboxes, DLLs, gateways, and details templates. The tool can also be used to load a header from an existing directory import or export file. You must run Import Header on a Microsoft Exchange Server computer, and the directory service must be running.


Using the Import Header Tool

Use the following procedure to run Import Header:

To create a header file

1. In the Tools\Headers directory on the Microsoft BackOffice Resource Kit: Part One compact disc, run Headers.exe.

2. When the Import Header tool finishes loading the schema, select either Import or Export under Directory Mode.

3. Under Object Class, select the type of object you want to import or export.

4. Under Available Attributes, select the attributes to include in the header file. Attributes displayed in bold are required for the selected object; dimmed attributes cannot be imported. For more information about directory attributes, see the Microsoft Exchange Server Migration Guide.

5. Choose Add to add the attributes from Available Attributes to Selected Attributes. Choose Remove to remove attributes from Selected Attributes. Note that if you remove required object attributes when creating an import file, objects may not be imported.

6. Select File to specify a text file to use as the header file. If you select an existing import/export file, the file's existing header is loaded into the Selected Attributes column.

7. Select Generate to add the selected attributes to the header file. The header file is now ready to be used for directory import and export.

Note

The Schema.hlp file provided in the Microsoft Exchange Server Software Developer's Kit describes all the attributes of the Microsoft Exchange directory service. Use this Help file with the Import Header Tool to determine which attributes to import or export.


IMC Configuration Restorer

The IMC Configuration Restorer is a command-line tool that exports specific Internet Mail Connector configuration information into a file so that it can be imported to another Internet Mail Connector.

In large organizations, the Internet Mail Connector for each domain routing and encoding configuration is extensive. For an administrator to duplicate the configuration manually on another connector can take hours and can also be prone to error. The IMC Configuration Restorer can save valuable time by automating the process of copying Internet Mail Connector configuration information to another Internet Mail Connector.

The IMC Configuration Restorer saves the following information:

  • Per-domain routes
  • Per-domain content encoding
  • Security exception list (accept/reject by host)
  • Multipurpose Internet Mail Extensions (MIME) types


Installing IMC Configuration Restorer

You can run the IMC Configuration Restorer from the Tools\Imccopy directory on the Microsoft BackOffice Resource Kit: Part One compact disc. No installation is required.


Using IMC Configuration Restorer

The two types of operations you can perform by using the IMC Configuration Restorer are:

  • Saving an item
  • Restoring an item

To save an item

· Type IMCCOPY [-?] -save [item][,item]] <file name>

- ? displays a usage message; no operation is performed.

-save takes the data in the existing configuration file and saves it to the specified file name.

The item option can be one of the following:

routes | per-domain routes
encoding | per-domain content encoding
security | accept/reject list
mime | MIME types
all | all of the above

If an item is not specified, a message with the proper use appears. A text file is created that contains the configuration information. You can view the file by using a text editor. If the file already exists, the message "existing files will not be overwritten" appears.

To restore an item

· Type IMCCOPY [-?] -restore | -merge [item[,item]] <file name>

-? displays a usage message; no operation is performed.

-restore overwrites the existing configuration with the new data.

-merge takes the new data and merges it into the existing configuration, replacing any conflicting entries with the new data.

The item option can be one of the following:

routes | per-domain routes
encoding | per-domain content encoding
security | accept/reject list
mime | MIME types
all | all of the above


IMC Sample Extension DLL

The IMC Sample Extension DLL intercepts inbound messages from SMTP hosts and selectively reroutes those messages to other SMTP hosts before they are processed by the Internet Mail Connector. This enables the Internet Mail Connector to act as a smart host that can route messages between the Internet and other SMTP hosts.

For example, if your organization uses multiple SMTP hosts, this extension enables you to designate the Internet Mail Connector as the single point of contact to the Internet. Other SMTP hosts can be configured to forward all messages to the Internet Mail Connector, where the extension will route messages appropriately.

The sample DLL modifies envelope addresses. However, it doesn't modify any message headers or the message body.


Installing the IMC Sample Extension DLL

The IMC Sample Extension DLL is included on the Microsoft BackOffice Resource Kit: Part One compact disc. You install the file to a server running the Internet Mail Connector.

To install the IMC Sample Extension DLL

1. From the Tools\Imcext directory on the Microsoft BackOffice Resource Kit: Part One compact disc, copy Imcext.dll to a server running the Internet Mail Connector.

2. Create a registry value named ExtensionDLL that points to Imcext.dll.

The key is HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIMC\Parameters. The type is REG_SZ. The value is c:\path\Imcext.dll, where path is the path to the sample extension DLL.

3. In the Imcdata directory on the Microsoft Exchange Server computer, create a configuration file named Imcroute.cfg.


Using IMC Sample Extension DLL

When initialized, IMC Sample Extension DLL loads a table named Imcroute.cfg from the configuration file you created. This file is in the directory specified in the RootDir IMC registry value.

Comparing Domain Names

The table contains a list of domain names and associated SMTP hosts. For each recipient of every inbound message the Internet Mail Connector receives, the IMC Sample Extension DLL must compare the domain name on the address to the list of domain names in the table. If a match is found, the message for that particular recipient is rerouted to the associated host.

The match is compared to the rightmost part of the domain name on the recipient address. For example, if the domain name in the table is sea.com, it matches an address of x.sea.com as well as sea.com. The list is searched from top to bottom, and the first match is used. Note that it's best to list more specific patterns before general ones to ensure that the names are found.

In cases where the associated SMTP host is localhost, domain names in the list represent names that should be handled by the Internet Mail Connector. If the recipient address matches one of these domain names, the Internet Mail Connector processes the recipient normally and attempts to deliver the message to the Microsoft Exchange Server. If no match is found, the IMC Sample Extension DLL reroutes the outbound message to the domain name in the recipient's address. For this reason, it is important to ensure that any domain names that must be routed to the Microsoft Exchange Server are listed in the configuration file. In particular, any domain names used in SMTP addresses for Microsoft Exchange users must be defined in the configuration file. Otherwise, reports and replies will not be deliverable and could cause routing loops.

It is possible to introduce a message routing loop if the configuration file contains incorrect or incomplete information. It is recommended that you enable the DisableLoopbackConnections Internet Mail Connector registry value to reduce the chance of a message routing loop occurring.

Configuration File Example

The following is an example of a configuration file.

! IMC Extension DLL Configuration File
! Event log parameters

EL_EventLogging

ReRouted

EL_EventLogging

NotRouted

Listserv.granite.com

listserv.granite.com

granite.sea.com

localhost

sea.com

mail.sea.com

granite.com

localhost

Lines beginning with an exclamation point (!) or a blank line are comments and are ignored. The keyword EL_EventLogging controls whether events are recorded to the Windows NT Workstation Event Log for messages that are processed. EL_EventLogging must be followed with ReRouted or NotRouted. ReRouted indicates that an event is recorded whenever an outbound message is rerouted. NotRouted indicates that an event is recorded whenever a message is not rerouted.

Message Routing Example

Given the previous configuration file, the following are examples of message routing based on matching the domain name in the recipient's address:

Recipient | Routed to
user@listserv.granite.com | listserv.granite.com
user@granite.sea.com | localhost
user@sea.com | mail.sea.com
user@granite.com | localhost
user@pike.granite.com | localhost
user@anything.else.com | anything.else.com


IMC Configuration Extractor

The IMC Configuration Extractor (Imcsave.exe in the Tools\Imcsave directory) is a command-line tool that extracts Internet Mail Connector messages and configurations from the Microsoft Exchange Server information store and directory. These messages and configurations are then restored on another computer.

This tool allows Microsoft Product Support Services to collect information for troubleshooting and to set up a matching configuration to reproduce problems. Use the IMC Configuration Extractor only with the assistance of Microsoft Product Support Services.


Using IMC Configuration Extractor

The IMC Configuration Extractor performs the following operations for collecting data and extracting Internet Mail Connector messages:

  • Looks in the registry to find the location of Imcdata, and then creates a directory called Backup under Imcdata. If the directory already exists, the process quits.
  • Copies all Internet Mail Connector service registry values to a file called Imcsvc.reg.
  • Copies all Internet Mail Connector profile registry values to a file called Imcpro.reg.
  • Uses directory application programming interface (DAPI) to export the gateway object to a file called Imcobj.csv.
  • Logs on to the service in the same manner as Internet Mail Connector.
  • Sets a flag immediately in the information store, which prevents more mail from being routed through Internet Mail Connector.
  • Creates a directory called Imcdata/Backup/Mtsout, and then copies all messages from MTS-OUT into that directory by using the transport-neutral encapsulation format (TNEF).
  • Creates a directory called Imcdata/Backup/Mtsin, and then copies all messages from MTS-IN into that directory.
  • Generates a packing list of all generated files called Imcfls, using an .ini format and code to encode the information.


Microsoft Exchange Server Address Export to MS Mail Tool

Microsoft Exchange Server Address Export to
MS Mail Tool

This tool (Eximwiz.exe) converts Microsoft Exchange Server Bulk Export format (.csv) to a MS Mail import format. After creating the output file, you can use the tool to interactively import the addresses into a MS Mail postoffice available on the network or send the import file through e-mail to external recipients.

This tool is useful in situations where directory synchronization between a Microsoft Exchange Server implementation and MS Mail is not a viable option. For example, if you are trying to populate a trading partner's MS Mail system with relevant addresses (such as purchasing agents) from your global address list.


Installing Microsoft Exchange Server Address Export to MS Mail

The Microsoft Exchange Server Address Export to MS Mail tool is included on the Microsoft BackOffice Resource Kit: Part One compact disc.

To install the Microsoft Exchange Server Address Export to MS Mail tool

1. Copy Eximwiz.exe from the Tools\Msmailex\Eximwiz directory to a directory of your choice.

2. Copy Msmapi32.ocx from the Tools\Msmailex\Eximwiz directory to your System32 or System directory.


Using Microsoft Exchange Server Address Export to MS Mail

Use the following instructions to export Microsoft Exchange Server Addresses to MS Mail.

1. In the Administrator program, export the addresses from the required container to a .csv file.

2. Run Eximwiz.exe.

3. Select the .csv file as the input file, and then select an output file to write the MS Mail import instructions to.

4. Select the user addresses that you want to process. If you want a majority of these user addresses processed, select the Add All option and then remove the addresses you don't want.

5. Select one of the following options:

  • Stop after creating the output file.
  • Send the file through e-mail to an MS Mail administrator.
  • Import this information directly into a MS Mail postoffice on the network.

6. Supply the additional information requested (for example, postoffice name, administrator ID and password for MS Mail directory import; and MAPI logon and recipient address information).


MS Mail SMTP Gateway Proxy Migration Tool

The MS Mail SMTP Gateway Proxy Migration tool (Migsmtp.exe) helps replace an MS Mail SMTP gateway with a Microsoft Exchange Internet Mail Connector by reducing the level of administrator intervention. It preserves current Internet addresses of the recipients and adds them as secondary proxies to the Microsoft Exchange Server global address list, which eliminates the need for the end-users to republish their new Internet address for their business associates. This tool is useful for the following scenarios:

Scenario | Action
Replace a single MS Mail SMTP gateway and associated postoffice with Microsoft Exchange and the Internet Mail Connector. | Migrate all users. Run Migsmtp.exe. Shut down the MS Mail SMTP gateway and put its IP address on the Internet Mail Connector computer.
Replace a MS Mail SMTP gateway and networked postoffices with multiple Microsoft Exchange servers and the Internet Mail Connector. | Migrate all users to servers. Visit each server and process recipients to assign proxies using Migsmtp.exe.
Replace a MS Mail SMTP gateway with the Internet Mail Connector and Microsoft Exchange Server. | Remaining postoffices are connected to Microsoft Exchange by using the MS Mail Connector.
Replace a postoffice server. | Perform directory synchronization. Modify proxies by using Migsmtp.exe. When you migrate users to Microsoft Exchange Server, rerun Migsmtp.exe to modify existing proxy addresses. This ensures that users maintain the addressing attributes they had in MS Mail.


Installing MS Mail SMTP Gateway Proxy Migration Tool

The MS Mail SMTP Gateway Proxy Migration tool is included on the Microsoft BackOffice Resource Kit: Part One compact disc.

To install the MS Mail SMTP Gateway Proxy Migration tool

  • Copy Migsmtp.exe from the Tools\Msmailex\Migsmtp directory on the Microsoft BackOffice Resource Kit: Part One compact disc to a Microsoft Exchange Server.


Using MS Mail SMTP Gateway Proxy Migration Tool

Run Migsmtp.exe at the command prompt on a Microsoft Exchange Server using the following form.

MIGSMTP [-?] [-R] [-V] [-Ccontainer] [-Taddresstype] -sserver -pPOpath

-? Displays Help.

-R Replace the primary SMTP proxy name. If not specified, the MS Mail SMTP proxy name is appended as a secondary SMTP proxy name.

-V Verbose progress reporting.

-C Processes only the recipients in container. If -C is not specified, only the Recipients container will be processed.

-T Uses addresstype as the type of the generated address instead of SMTP.

-s server is the name of the Microsoft Exchange Server to run the process on.

-p POpath is the path to the MSMail postoffice. The Addr_map.cfg and Local.cfg files are required by the proxy generation process. These files must be located in the path specified either in a live database in the directory, or as separate files in the directory.

Migsmtp.exe adds an SMTP secondary proxy for each user that is located by converting their MS Mail address (type MS in Microsoft Exchange Server). The MS Mail address is searched for in the following order:

1. The target address in a custom recipient

2. The primary proxies

3. The secondary proxies

This transformation is not performed on custom recipients with a target address of type SMTP.

SMTP address generation also takes place for distribution lists and recipients hidden from the Address Book.


MS Mail Proxy to Microsoft Exchange ProxyConversion Tool

MS Mail Proxy to Microsoft Exchange Proxy
Conversion Tool

This tool converts existing SMTP/MHS/X.400 addresses from an MS Mail Export format to Microsoft Exchange Bulk Import format (.csv) so that they can be added as custom recipients to a Microsoft Exchange Server Recipient container.


Installing the Proxy Conversion Tool

The MS Mail SMTP Gateway Proxy Migration tool (Perl.exe) is included on the Microsoft BackOffice Resource Kit: Part One compact disc.

To install the Proxy Conversion tool

· Copy the following files from the Tools\Msmailex\Proxy directory of the Microsoft BackOffice Resource Kit: Part One compact disc to a directory of your choice.

Perl.exe

Perl100.dll

Convert.pl

Go.bat (Sample file optional)

In.txt (Sample file optional)

Out.txt (Sample file optional)

Fail.txt (Sample file optional)

For more information on the PERL program, see the Microsoft Windows NT Resource Kit version 3.51.


Using the Proxy Conversion Tool

1. Run Import.exe against an existing MS Mail postoffice.

2. Type the following:

PERL <input_file > <output_file>

where input_file is the file created in step 1, and output_file is the .csv file for the conversions.

3. Using the Administrator program, import the .csv file to add the addresses as custom recipients to a Microsoft Exchange Server Recipient container.

Sample Files

The following sample files are included on the compact disc:

  • In.txt (sample input file)
  • Go.bat (sample command file)
  • Out.txt (sample output file)
  • Fail.txt (sample error file)


RPC Counter Tool

The RPC counter is a performance tool that checks the number of RPCs from an application to a Microsoft Exchange Server. The RPC counter is used with clients running Windows 3.1, Windows for Workgroups, Windows NT Workstation, and Windows 95.

It's always important to design your application for maximum performance. Minimizing the number of RPCs for your application is the most important factor in improving performance. The RPC counter can alert you to less efficient code processes so that you can optimize these areas. Using the RPC counter to minimize the number of RPCs can improve your application's performance and decrease the load on the Microsoft Exchange Server computer.

The RPC counter is useful for determining the number of RPCs that are generated by:

  • MAPI calls
  • User actions
  • An application

All these examples for using the RPC counter are useful in determining the effect of system performance on the Microsoft Exchange Server from various sources.


Installing RPC Counter

Before you can use the RPC counter, you need to connect with the Emsmdb(32).dll file, which contains the necessary entry points for generating the RPC data. For details on RPC counter entry points, see "Understanding RPC Counter Entry Points" later in this appendix. The Emsmdb(32).dll file is part of the Microsoft Exchange Client and Microsoft Exchange Server installation and is located in the Windows\System(32) directory.

You can access RPC counter data through several sample applications, depending on the your computer's operating system.

To install the RPC counter sample applications

· Copy the appropriate file from the Tools\Rpc directory on the Microsoft BackOffice Resource Kit: Part One compact disc to your current working directory or somewhere in the system path.

For Windows NT Workstation and Windows 95, copy Rpccnt.exe.

For Windows 3.1 and Windows for Workgroups, copy Rpccnt16.exe.

When you run these files displays, the RPC counter appears in a dialog box.


Using RPC Counter

On the Windows 3.1 and Windows for Workgroups platforms, the RPC counter does not require any special setup.

To use RPC Counter on Windows NT Workstation and Windows 95 platforms

1. Set the following registry value to DWORD=1:

HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Exchange Provider\RpcCounter

2. Restart all MAPI applications for the change to take effect.

Running Rpccnt.exe automatically sets the registry value to enable the RPC count.

Understanding the Fields of the RPC Counter

The RPC counter consists of the following nine fields, which indicate the number of RPCs generated for particular processes occurring on a Microsoft Exchange Server.

Total RPCs (IS+DS) The number of RPCs going from all Microsoft Exchange clients on a given computer to all Microsoft Exchange Server computers they are connected to. This number includes RPCs to both the information store and the directory.

DS RPCs

The number of RPCs going to the directory. They are generated by MAPI calls related to address name resolution. All RPCs in this category need to be monitored carefully when optimizing MAPI clients. Note that DS RPCs are not counted on Windows 3.1 and Windows for Workgroups platforms.

IS RPCs

The total number of RPCs going to the information store. This number is the result of either MAPI calls accessing the message data or is generated automatically by the store provider code.

IS Bytes Out

The total number of bytes sent. It does not include the overhead of the RPC protocol. For example, the number reported by the network tools will be approximately 300 bytes higher per RPC.

IS Bytes In

The total number of bytes received. It does not include the overhead of the RPC protocol. For example, the number reported by the network tools will be approximately 300 bytes higher per RPC.

Progress RPCs (IS)

Indicates the RPCs generated automatically by the information store provider to monitor the progress of long operations.

Resent RPCs (IS)

Indicates the RPCs generated automatically by the information store provider if the RPC buffer is too small and the data needs to be resent.

Poll RPCs (IS)

Indicate the RPCs generated automatically by the information store provider to check for pending notification or to get the data after receiving a push notification.

Indicates the RPCs generated directly by a MAPI call. This is the most important number to monitor when optimizing MAPI clients.

In addition, the RPC Counter dialog box displays an Auto Reset check box and a Reset Now button. The Auto Reset check box causes the counter data to be reset after four seconds of idle time. The Reset Now button resets the counter immediately.

Understanding RPC Counter Entry Points

When using the Rpccnt(16).exe sample application, the file calls the appropriate Emsmdb(32).dll entry points to obtain the counter data. The information in this section is provided if you need to call the entry points directly (for example, to integrate the RPC counter with other performance tools). The macro in Rpccnt.xls is an example of how to access the counter data from Visual Basic code.

The Emsmdb(32).dll file contains three entry points necessary for accessing RPC data. These entry points are the same for Windows 3.1, Windows for Workgroups, Windows NT Workstation, and Windows 95 platforms.

The three entry points are:

  • ScStatOpen, which initializes the count.
  • ScStatCollect, which collects the data.
  • ScStatClose, which closes the counter.

Examples

The following examples show the entry point declarations in both C and Visual Basic syntax:

C Syntax

SCODE FAR PASCAL ScStatOpen(void);
SCODE FAR PASCAL ScStatClose(void);
SCODE FAR PASCAL ScStatCollect(struct RPCStat *rgStat, ULONG *pcbStat);
Visual Basic Syntax

Declare Function ScStatOpen Lib "EMSMDB.DLL" () As Long

Declare Function ScStatClose Lib "EMSMDB.DLL" () As Long

Declare Function ScStatCollect Lib "EMSMDB.DLL" (ByRef rgStat As RPCStat, ByRef cbStat As Long) As Long

Because the data counting begins when ScStatOpen is called, a call to ScStatClose followed by ScStatOpen resets the counter. Because Windows NT Workstation and Windows 95 platforms have a per-instance data segment, you might have several counters counting independently. Windows 3.1 and Windows for Workgroups, however, have a shared data segment; therefore, resetting the counter is global to all instances.

Understanding the RPCStat Structure

The RPCStat structure contains the RPC counter values. These values are generated in the fields described previously in "Understanding the Fields of the RPC Counter." The RPCStat structure used by the entry points are:

C Syntax

struct RPCStat
{
  ULONG    cRPC;
  ULONG    cProgressRPC;
  ULONG    cResentRPC;
  ULONG    cPollRPC;
  ULONG    cbRPCOut;
  ULONG    cbRPCIn;
  ULONG    cDSARPC;
};
Visual Basic Syntax

Type RPCStat
  cRPC As Long
  cProgressRPC As Long
  cResentRPC As Long
  cPollRPC As Long
  cbRPCOut As Long
  cbRPCIn As Long
  cDSARPC As Long
End Type

The ScStatCollect entry point has a pointer as an argument to the RPCStat structure (allocated by the caller) and a pointer to a long variable containing the size of the RPCStat structure in bytes. On return, if there is no error (return value = 0), the RPCStat structure is updated with the counter values and the size variable is updated with the returned data size. If an error occurs (for example, out of memory), the returned value is non-zero.


Bulk Advanced Security Tool

The Bulk Advanced Security tool (Sectool.exe) encrypts and decrypts messages in folders and subfolders in a user's private information store or personal folder file (.pst file). This tool is most useful for moving messages in security-enabled mailboxes between sites and between recipient containers. It can also be used to secure messages in confidential folders. You can do the following with the Bulk Advanced Security tool:

  • Decrypt all messages in a folder and its subfolders.
  • Encrypt all messages in a folder and its subfolders.
  • Encrypt only messages that were previously decrypted with this tool.


Moving Messages to a New Security-Enabled Mailbox

Without the Bulk Advanced Security tool, users can't open encrypted messages from their old mailbox in their new mailbox. Because a user's security file (.epf file) and security keys are associated with a user's mailbox, the old .epf file can't be used after the mailbox is moved. A new .epf file must be created for the mailbox by following the advanced security setup procedure.

To move encrypted messages from one site to another, users first move their messages to their .pst files and decrypt their messages by using the Bulk Advanced Security tool. After the messages have been moved to the new mailbox, they can be encrypted again with the Bulk Advanced Security tool. For more information on moving mailboxes between sites or recipient containers, see the Microsoft Exchange Server Administrator's Guide.


Using the Bulk Advanced Security Tool

Use the following procedures to decrypt and encrypt messages:

To decrypt messages in a folder

1. In the Tools\Security directory on the Microsoft BackOffice Resource Kit: Part One compact disc, double-click Sectool.exe.

2. From the Exchange Security menu, choose Unsecure Folder.

3. Type your security password, and then choose OK.

4. Select the message store containing the messages you want to decrypt, and then choose OK.

5. Select the folder containing the messages you want to decrypt, and then choose Start Here. To select a subfolder, choose Open Folder.

6. Select Process Subfolders to decrypt messages in the selected folder and its subfolders, and then choose OK.

To encrypt messages in a folder

1. In the Tools\Security directory on the Microsoft BackOffice Resource Kit: Part One compact disc, double-click Sectool.exe.

2. From the Exchange Security menu, choose Secure Folder.

3. Type your security password, and then choose OK.

4. Select the message store containing the messages you want to encrypt, and then choose OK.

5. Select the folder containing the messages you want to encrypt, and then choose Start Here. To select a subfolder, choose Open Folder. If you are moving messages between sites or recipient containers, select the folder containing the messages you decrypted before the messages were moved.

6. Select the options that you want to use for encrypting messages, and then choose OK.

Option | Description
Re-secure previous secure messages | Encrypts only messages that were previously decrypted by this tool.
Encrypt all messages in folder | Encrypts all messages in the folder that were not previously encrypted.
Encrypt Signed Messages | Encrypts messages that are secured with digital signatures. If selected, digitally signed messages will be encrypted but no longer signed.
Process Sub Folders | Encrypts all messages that were not previously encrypted in the folder and its subfolders.


Command Line Mail Sender

The Command Line Mail Sender (Sendmail.exe) is used to send messages with optional file attachments through Microsoft Exchange Server from a Windows NT Workstation or Windows 95 command prompt.

Computers running Windows NT Workstation or Windows NT Server unattended, can better communicate their status proactively, rather than constantly being polled by remote performance monitors or operations staff using Windows NT Server administration tools. Command Line Mail Sender was developed to enable the following tasks to be reported to an operations group using standard Microsoft Exchange Server messages:

  • Performance Monitor alerts
  • Tape backup job status
  • Disk quota information (using Diruse)


Installing Command Line Mail Sender

Before you can install the Command Line Mail Sender, you must have either Microsoft Exchange Server or the Microsoft Exchange Client running on your computer.

To install the Command Line Mail Sender

· From the Tools\Sendmail directory on the Microsoft BackOffice Resource Kit: Part One compact disc, copy Sendmail.exe to your working directory or somewhere in the system path.

If you want to run Sendmail.exe using Windows NT Workstation, you need to set up a new account for Sendmail.exe to run under as follows:

1. Log on to a Microsoft Exchange Server as a domain account.

2. Create a new Windows NT account that Sendmail.exe can use to access the Microsoft Exchange Services.

3. Create a profile for the new account.

4. Make the domain account you are logged on to the Schedule+ service logon account.

5. In the Administrator program, grant the new account the Send As or Mailbox Owner permission on the Permissions tab.


Using Command Line Mail Sender

The Command Line Mail Sender takes the command-line arguments you pass it and calls three basic MAPI functions: Logon, SendMail, and Logoff. The tool then pauses for one second and lets other MAPI threads, namely the Spooler, deliver your message before it quits. This is done so that the client does not need to be loaded to use the Command Line Mail Sender, and the message is delivered before the Command Line Mail Sender quits.

At the command prompt, type:

SENDMAIL -u profile name -p password -r recipient(s) [-c copy recipient(s)] [-s subject] [-m message] [-f file attachment(s)] [-v] [-?]

Use the profile name specified when you choose Mail and Fax in Control Panel. If there are spaces in the name, enclose the name in quotation marks.

Examples

In this example, a message from user RISNT01 is sent to Technicians 1, 2, and 3 with a copy to local area network (LAN) Support. The subject is "[411] Server Alert" with a message "Disk is 90% full." The two log files are attached to the end of the message.

Instead of hard coding the subject line and message text, you can retrieve specific details from the Performance Monitor alert with the command-line arguments %0, %1, %2, and so on, to construct a meaningful Command Line Mail Sender message.

1. Run the Srvany.exe utility in the Windows NT Resource Kit to set up Performance Monitor to run as a service.

2. Add an alert that starts when the disk drive is more than 90 percent full.

3. In the Alert Send window, run the Command Line Mail Sender by typing the following in the Run Program on Alert box:

SENDMAIL -u RISNT01 -p -r tech1;tech2tech3 -c "LAN Support" -s

"[411] ServerAlert" -m "Disk is 90% full" -f

c:\temp\diruse.log;c:\temp\status.log


Avoiding Recipient Ambiguity Problems

Recipient ambiguity problems can occur when using the Command Line Mail Sender. Recipient names entered in the To and Cc boxes must not be ambiguous; otherwise, the Command Line Mail Sender will fail.

To test for ambiguity of names

1. Type the recipient names in the To box of a Microsoft Exchange Client standard send form.

2. Choose To, or press CTRL+K.

If the names are immediately resolved without any prompting, they are not ambiguous.

3. Repeat this test each time the Address Book is changed, and run the test from the computer where Command Line Mail Sender runs.


Mailbox Statistics

You can use the Mailbox Statistics tool (Storstat.exe), to gather data about mail use patterns. This MAPI application analyzes a responding user's set of personal folders and then develops statistics, such as the number of rules in a folder and the amount of mail sent and received daily. You can gather statistics about users who run Microsoft Exchange with either the Windows 95 or the Windows NT Workstation operating system.

Then you can export this data into several formats, including .txt and .csv. A Microsoft Visual Basic macro that runs under Microsoft Excel is also included. You can this macro use to explore Mailbox Statistics results in more detail. Using Microsoft Excel, you can customize column names, convert the data into a chart, or otherwise manage Mailbox Statistics results.

You can run Mailbox Statistics anytime. A frequency of about once every six months is typical. You can use it to establish use patterns, to determine when a server load should be re-balanced, or when you need data for the Microsoft Exchange Server Load Simulator (LoadSim) that more closely reflects your users.

Mailbox Statistics creates some load on the server, so it's best not to use it during peak hours. Also, you can divide your users into groups and spread your study over a day's time. For example, you can survey your accounting staff at 9 A.M. and your marketing staff at 11 A.M.


Installing Mailbox Statistics

You install Mailbox Statistics by copying its files from the Microsoft BackOffice Resource Kit: Part One compact disc to a Microsoft Exchange Server computer.

To install Mailbox Statistics

· Copy the Tools\Storstat directory to your Microsoft Exchange Server computer.

This directory contains StorStat.exe, which can be used by Windows 95 and Windows NT Workstation users.


Using Mailbox Statistics

When you use Mailbox Statistics, you set up an administrator's mailbox for collecting results and send the tool to your users to run it against their sets of personal folders. When user's submit a number of results, you can run the tool in administrator mode and export results to a variety of output formats. Before you send the tool to your users, you can test it with a smaller subset of about 10 people to ensure the tool works as expected and to become familiar with the different kinds of results.

Note that mailbox Statistics can detect only Microsoft Exchange Server distribution lists (DLs).

If the Save Items to Sent Mail option is not selected in a user's Microsoft Exchange setup, then Mailbox Statistics cannot determine the number of messages sent per day. You can ask the test group to select this option for at least seven days before the study to collect enough information to use.

To use Mailbox Statistics:

  • Set up an administrator's mailbox that will be used to receive the data
  • Send a message with Storstat.exe attached to the users to be surveyed. Those users double-click an icon in the message to run it.

Note

Storstat.exe is supported only for users on Windows 95 or Windows NT Workstation.

To set up the Administrator's mailbox

1. Using the Microsoft Exchange Server Administrator program, create a mailbox with the display name StorStat.

2. Set permissions on this mailbox according to your organization's procedures so that the Microsoft Exchange Server administrator's account has user permission on this mailbox.

Results appear as MAPI messages with the subject "UserName UserResults." You can use the Inbox Assistant to forward or copy results to another folder.

To send mailbox statistics to users

1. From the Microsoft Exchange Client Compose menu, choose New Message.

2. In the message body, type instructions for your users.

3. From the Insert menu, choose File, and then attach StorStat.exe to the message.

It appears as an icon in the message.

Users can be concerned about using the tool if they believe it will alter, damage, copy, or intrude in any way on their sets of personal folders. For this reason, you can include information to reassure them that no information is read or copied, no damage is inflicted on their data, and no changes are made to their data when this tool is running.


How a User Works with Mailbox Statistics

The user opens the message and starts a copy of the tool, which opens the Message Stores Statistics Analyzer dialog box listing all the user's personal folders. At least one message store must be selected before analysis can be started.

By default, all personal folders are selected. The user can choose Clear All to cancel the selection and then select specific folders to analyze, or choose Select All to select all the personal folders. If the user chooses Exit, no analysis is performed.

When the user chooses Start Analyzing, the tool opens and analyzes every personal folder file owned by that user. The tool then generates statistics, including the number of folders, the number of rules, and the amount of e-mail per day in each folder. A progress bar and the folder names are displayed as messages are processed.

When the Mailbox Statistics tool finishes analyzing the folders, it displays the following message: "Results have been automatically sent to your administrator. Thank you for your cooperation." Optionally, the user can also save the results. When the user deletes the announcement message, StorStat.exe is also deleted.


Running Mailbox Statistics in Administrator Mode

This procedure assumes that an administrator's mailbox (named StorStat) has been created and is available to collect results from users. You can check on the number of responses by opening the Inbox and viewing the number of messages containing "UserResults." When enough responses have been gathered, you can tabulate them by running the Mailbox Statistics tool in administrator mode.

If you have results generated by an earlier version of the tool, store them separately from later results. With the results separated, you should receive no error messages caused by using the tool on mixed-version generated results.

If you want to use the macro included with Mailbox Statistics, save your results in the Microsoft Excel .csv file format.

To run Mailbox Statistics in Administrator mode

1. At the command prompt, type:

storstat.exe -a

2. Set the default messaging profile to the Mailbox Statistics administrator's mailbox, or select the profile.

You'll see a progress bar move as messages are processed. When all messages are processed, the Summary Results dialog box appears.

3. Choose Save As to save results in a location under a file name you specify, or choose Exit to disregard these results.

Exporting Results

When the Mailbox Statistics tool completes its analysis of each set of personal folders, it sends a message to the administrator's mailbox you set up for collecting the results. When you run the tool in administrator mode, you can save your results as many times as you want, using different file types.

To export your results

1. Run Mailbox Statistics in administrator mode.

2. In the Save As dialog box, select a file type for your results.

Interpreting Results

Remember that Mailbox Statistics works with available data. For example, if a few users empty the Deleted Items folder when quitting Microsoft Exchange, and others do not, you can see wide differences between the statistics calculated from the Deleted Items folder. Moreover, Forward and Reply may not be computed as expected with localized Microsoft Exchange clients because the logic looks for RE: and FW: characters.

The first time you review the results, use the following example to become familiar with the local source of each statistic.

Sample Mailbox Statistics Results

The following two sections list captions that precede each statistic the Mailbox Statistics tool displays. The first illustrates statistics from a single set of personal folders. The second illustrates statistics from combined sets of personal folders collected in an administrator's mailbox.

If the caption is self-explanatory, no note is included. If a note is included, it follows the caption and is enclosed in brackets. Notes either define terms or clarify logic.

**************************************************

Service Provider: Personal Folders.

Message Store: Archive.

**************************************************

Total msgs in entire store: 575.

Total msgs in received mail folder: 80.

[By default, the received mail folder is the Inbox.]

Total msgs in sent mail folder: 10.

[If this number of 0, it’s possible the Save Mail in Sent Items option has been turned off. If this option is off, then a number of other statistics related to outgoing mail will also be 0.]

Total msgs in Deleted Items folder: 67.

Total number of non-standard top level folders is 21.

[A standard folder cannot be deleted by a user, and includes the Inbox, Sent, Deleted Items, and Outbox folders.]

Average number of subfolders of top level folders is 0.12.

[The total number of folders is divided by the total number of subfolders.

Average depth of top level folders is 0.04.]

[Depth implies how "far down" subfolders exist. For example, an Inbox with a subfolder would generate a depth of 2.]

Total msgs in msg store with at least one attachment is 118.

[An attachment can be a file, a message, or a link.]

Percentage of the total msgs in the store that contain at least one attachment is 20%.

[Number of messages with attachments divided by total number of messages, converted to a percentage.]

Average msgs sent per day is 0.00.

[This average is calculated using the number of days in the sample.]

Average msgs sent per day (real) is 0.00.

[This average is calculated using all the days between the first and last date that a message was sent. This number also includes days when no messages were sent. So, for example, if a user sent mail on Monday, Wednesday and Friday, ‘sent per day’ would be divided by 3 and ‘sent per day (real)’ would be divided by 5.]

Largest number of msgs sent a day is 0

[A day is defined as midnight to midnight and is not configurable.]

Largest number of recipients on a message is 0

[A recipient can be either a single recipient or a single distribution list (DL).]

Average number of recipients on all sent msgs is 0.00.

[Total number of recipients on sent messages divided by the number of messages sent.]

Average number of DL recipients on all sent msgs is 0.00.

[Total number of DLs on sent messages divided by the total number of messages sent. If you are using a different mail system to control DLs, then the number sent to DLs will be lower than expected. Mailbox Statistics detects only Microsoft Exchange Server DLs.]

Percentage of the total msgs sent to at least one DL is 0%.

[Number of sent messages with at least one DL divided by the total number of messages sent.]

Total msgs sent to at least one DL is 0.

Average number of replies per day is 0.00.

[Number of replies, message subject prefix equals RE:, divided by the number of days messages were sent.]

Average number of forwards per day is 0.00.

[Number of forwards, message subject prefix equals FW:, divided by the number of days messages were sent.]

Average number of replies per day (real) is 0.00.

[Number of replies, message subject prefix equals RE: divided by the total number of days surveyed.]

Average number of forwards per day (real) is 0.00.

[Number of forwards, message subject prefix equals FW:, divided by the total number of days surveyed.]

Percentage of sent messages that were replies is 0%.

[Total number of sent messages that were replies divided by the total number of sent messages.]

Percentage of sent messages that were forwards is 0%.

[Total number of sent messages that were forwards divided by the total number of sent messages.]

Combined size of all messages in message store 19318K.

[Cumulative size of all messages as reported by MAPI. Don’t be concerned by the relationship between the size of the private information store (Priv.edb) database file and the total message store size reported by Mailbox Statistics, because they do not correspond one-to-one.]

Folder with the largest combined size of messages had 9062K in it.

[This is the sum of all message sizes in a single folder. It does not include subfolder totals.]

Largest # of messages in any folder 106.

Average size of messages per folder 689.93K.

[Total size of all messages divided by the number of folders in a store.

Total number of folders in message store 28.

[Total number of messages in the message store, including the standard folders, Inbox, Outbox, Sent Items, and Deleted Items.]

Max depth of folders is 2.

[Depth implies how "far down" subfolders exist. For example, an Inbox with a subfolder generates a depth of 2.]

Average # of msgs received per day 6.75.

[Total number of messages in a store divided by the number of days during which a message was received. This number can be skewed if a message is copied multiple times within a store or if the Empty the Deleted Items Folder upon Exiting option is selected.]

Average # of msgs received per day (real) 3.28.

[Total number of messages in a store divided by the total number of days.]

Maximum # of msgs received in a day 54.

Number of Inbox rules is 0.

[Number of Inbox Assistant rules including Out of Office Assistant rules.]

**************************************

Results for provider: Combined Message Stores.

**************************************

Number of result messages for this provider: 0.

Average # of messages in Inbox: 0.0.

Average # of messages in Sent Items: 0.0.

Average # of messages in Deleted Items: 0.0.

Highest number of additional folders of any message store: 0.

[This number excludes the standard folders, which are Inbox, Outbox, Sent Items, and Deleted Items.]

Lowest number of additional folders of any message store: 0.

Average number of additional folders for all message stores: 0.0.

Number of msgs total for all message stores: 0.

Percentage of those msgs that contain at least one attachment: 0%.

Largest number of msgs in any message store: 0.

Average number of msgs per message store: 0.0.

Average number of msgs sent per day: 0.0.

Average number of msgs sent per day (real): 0.0.

Highest number of msgs sent per day: 0.

Lowest of the maximum sent per day: 0.

[If this number is 0, a user may have either emptied the Sent Items folder or sent no mail in a day.]

Average number of recipients per sent msg: 0.0.

Average number of distribution lists per sent msg: 0.0.

Total number of messages sent to at least one DL: 0.

Percentage of total messages sent to at least one DL: 0%.

Avg # of subfolders of top level folders: 0.0.

Avg depth of top level folders: 0.0.

Largest # of recipients on a single message: 0.

Average # of replies per day: 0.0.

Average # of forwards per day: 0.0.

Average # of replies per day (real): 0.0.

Average # of forwards per day (real): 0.0.

Percentage of sent messages that are replies: 0%.

Percentage of sent messages that are forwards: 0%.

Percentage of sent messages that were originated: 100%.

[100 percent minus the percentages of replies and forwards.]

Combined size of all messages: 0K.

Average message size: 0.0.

Folder containing largest size of messages: 0K.

Folder containing largest # of messages: 0.

Average # of messages per folder: 0.0.

Total # of folders: 0.

[Total number of folders for all clients, including the Inbox, Outbox, Sent Items, and Deleted Items for each.]

Avg # of folders per message store: 0.0.

Largest # of folders per message store: 0.

Deepest folder tree: 0.

Avg # of messages received per day: 0.0.

Avg # of messages received per day (real): 0.0.

Largest # of messages received per day: 0.

Total # of Inbox rules: 0.

Largest # of Inbox rules: 0.

Avg # of Inbox rules: 0.0.

Questions and Answers

The following are common questions and answers about the Mailbox Statistics tool:

Q: Why haven't I received any results in the administrator's mailbox?

A: Check the installation of the Mailbox Statistics tool, including these verifications:

  • The administrator's mailbox name is correct.
  • Instructions and StorStat.exe were received by the users.
  • At least one user successfully completed the survey.
  • Microsoft Exchange Server is transferring e-mail successfully.

Q: Why didn't we receive all the results?

A: Each user can decide whether to run Mailbox Statistics. Some time may lapse before all the results are sent, especially if you gave no deadline, or if some users are away from the office. If the number of results is low, verify that all users received the instructions and the Mailbox Statistics tool, and then send a reminder to run the survey.

Q: Why can't Windows for Workgroups or Windows 3.1x users run the tool?

A: Mailbox Statistics is a 32-bit tool. It can be used only with Windows 95 or Windows NT Workstation operating systems.


Additional Information

Many resources are available that provide additional information about Microsoft Exchange Server.


Microsoft BackOffice Resource Kit: Part One Compact Disc

The Microsoft BackOfficeä Resource Kit: Part One compact disc contains the tools described in Appendix E, "Tools."


Web Sites

Visit the following Web sites for up-to-date information about the Microsoft Exchange Server product.

http://www.microsoft.com/exchange

The Microsoft Exchange Server Web site contains up-to-date information about Microsoft Exchange Server and links to other Microsoft BackOffice products.

http://www.microsoft.com/support/products/backoffice/msmail.htm

The Microsoft Exchange Server Technical Support Web site gives you access to the Microsoft Exchange Server knowledge base, support information, and frequently-asked questions.

http://www.microsoft.com/technet

The Microsoft TechNet Web site contains information about subscribing to Microsoft TechNet, which provides in-depth technical information about Microsoft business products, including Microsoft Exchange Server and other Microsoft BackOffice products.

http://www.microsoft.com/train_cert

The Microsoft Training and Certification Web site provides information about training options and the Microsoft Certified Professional Program.


Contributors

Technical Writers:

Karen Greytak, Brad Joseph, Kristina Marx, Lisa Matheson, and Renée K. Smith

Technical Consultants:

Pilar Orozco Ackerman, Marc Allen, Kali Buhariwalla, Angel Calvo, John Chen, Jim Chismar, Behrooz Chitsaz, Tom DeFeo, Matthew Durasoff, Charles Eliot, Hal Howard, David Johnson, Mark Ledsome, John S. Lee, Eric Lockard, Iain McDonald, Moon Mulligan, Susan Nellis, Ramez Naam, Brent Prindle, Jim Reitz, Rob Sanfilippo, Naresh Sundararajan, Mike Sartain, Doug Strauss, and Rebecca Wynne

Technical Editors:

Sharon Farrar, Connie La Chasse, and Linda Sandstrom

Team Managers:

Deborah Annan and Bonita Sargeant

Indexer:

Ronnie Maier

Production:

Ellen Brenner, Erin Pearson, Colleen Tremaine-Nelson, and Todd White

Lead Graphic Designer:

Autumn Sheppard

Graphic Design Support:

Chris Blanton, Gabriel Varela, and Sue Wyble

Administrative Assistant:

Amy Hirsh


Introduction

Welcome to the Microsoft SQL Server Resource Guide. This guide is designed for people who are, or want to become, expert users of Microsoft® SQL Server™.

If you are responsible for designing a database solution, administering one or more SQL Server databases, or programming applications to streamline database activities, this guide is for you. It has been compiled largely from articles written by Microsoft staff in answer to frequently asked questions and to provide insights and usage ideas.

In addition to the information in this guide, various SQL Server utilities are included on the Microsoft BackOffice™ CD-ROM. Throughout the guide, you will learn about different uses for SQL Server. Demonstrations of these product applications can be found on the CD-ROM. If you develop SQL Server database systems, you can pick up code snippets from the CD-ROM. Also included on the CD-ROM are product add-ons and stand-alone applications you can use to simplify your administration duties.

The Microsoft SQL Server Resource Guide supplements the documentation included as part of the Microsoft SQL Server product and does not replace the documentation as the source for learning how to use Microsoft SQL Server.


About the Resource Guide

Part 1, Product Guide and Strategies

Discusses the benefits of SQL Server, how it enforces data integrity, and its scalability on the Windows NT® Server operating system. Additionally, you will gain insight on using SQL Server for Web solutions.

Part 2, Understanding SQL Server Architecture and Components

Describes in greater detail the architecture of SQL Server, the internal structure of the database, and Microsoft Distributed Transaction Coordinator.

Part 3, Planning and Implementing Your SQL Server Solution

Provides information to help you plan, design, and implement your SQL Server architecture. Backup and recovery, database-Web connectivity, efficient queries, and hardware planning are discussed here.

Part 4, Maintaining Your SQL Server Solution

Demonstrates everyday maintenance tasks on your SQL Server. You will learn tips about upgrading, managing replication, checking database consistency, scheduling database tasks, and tuning.

Part 5, Integrating with BackOffice

Describes how you can use SQL Server with the Microsoft BackOffice family.

Part 6, Programming for Microsoft SQL Server

Provides information that will help you incorporate your program into the SQL Server framework.

Part 7, Data Warehousing

Discusses the use of SQL Server as a data warehouse. A demonstration of a data warehouse using Microsoft technology is included on the CD-ROM.

Part 8, Reference

Provides information about changes to SQL Server from version to version, SQL Server code pages, database size estimates, and locking.

Part 9, Tools

Discusses the SQL Server tools included on the BackOffice Resource Kit CD-ROM, including installation instructions, descriptions, and usage.


Additional Information

Visit the following Web sites for up-to-date information about Microsoft SQL Server.

http://www.microsoft.com/sql

The Microsoft SQL Server Web site contains up-to-date information about Microsoft SQL Server and links to information about other Microsoft BackOffice products.

http://www.microsoft.com/support

The Microsoft SQL Server Technical Support Web site gives you access to the Microsoft SQL Server Knowledge Base, support information, and frequently asked questions (FAQs).

http://www.microsoft.com/technet

The Microsoft TechNet Web site contains information about subscribing to Microsoft TechNet, which provides in-depth technical information about Microsoft business products, including Microsoft SQL Server and other Microsoft BackOffice products.

http://www.microsoft.com/train_cert

The Microsoft Training and Certification Web site provides information about training options and the Microsoft Certified Professional Program.

http://www.microsoft.com/msdn

The Microsoft Developer Network Web site provides programming resources and information.


Conventions Used in This Guide

The following table summarizes the typographical conventions used in this guide.

Convention | Description
bold | Menus and menu commands, command buttons, toolbar buttons, tab and dialog box titles and options, command-prompt commands, and portions of syntax that must be typed exactly as shown. Bold is also used for elements of a SQL Server database such as table, column, view, index, device, and server names, data types, and configuration and database options as well as Transact-SQL stored procedures.
Initial capitals | Names of applications, file names, and directories in a path.
Italic | Information you provide, terms that are being introduced, and book titles.
Monospace | Example code, statements, and commands, program code and program output.


Part 1 - Product Guide and Strategies

Part 1 provides articles that address the ways you can use Microsoft SQL Server to streamline your database processes:

  • Microsoft SQL Server Data Integrity
  • SQL Server Scalability on Windows NT Server
  • Publishing Data on the Internet


Microsoft SQL Server Data Integrity

Microsoft SQL Server data integrity makes it the ideal product to satisfy your data accuracy needs.

In a single-user database, users can read and modify data without worrying that other users are changing data simultaneously. In high-volume, multiuser databases, such as Microsoft SQL Server, hundreds or even thousands of users may be executing queries and transactions against the same data concurrently.

Two key roles of the multiuser database are to:

  • Ensure that multiple concurrent transactions can produce the same effect as if they were executing in isolation.
  • Coordinate changes to data in a way that is consistent with organization-wide policies.

A critical issue of multiuser database design and implementation is how to control data integrity and concurrency in a way that supports the following conditions:

  • Many users can have coordinated access to the same data at the same time.
  • A user always sees a consistent view of the data and is prevented from making changes that would make the data inconsistent.
  • Data integrity is enforced within a single server and across multiple servers so that the data always reflects appropriate organizational and business policies.

If a database management system fails to implement the appropriate data concurrency, integrity, and consistency features, users can experience significant problems: lost updates, inconsistent data, and inaccurate results.


Server-enforced Data Integrity

Data in a database must be safeguarded for accuracy, consistency, and authorized access. Microsoft SQL Server actively protects the accuracy and consistency of data in demanding multiuser database environments. Microsoft SQL Server addresses this key area with a programmable server, which allows organization-wide data integrity, business rules, and transactions to be programmed into the server and shared among all client applications.

This programmable server enforces data integrity within the database itself, guaranteeing that complex business policies are followed. Since all rules are stored with the data and the single control point for data consistency is on the server, the need for these rules in every front-end application is eliminated. When rules change or new rules are created, they're encoded in only one place—the SQL Server database itself.

In addition, Microsoft SQL Server provides unique support for distributed data integrity, which ensures the accuracy and consistency of data distributed across multiple servers. By ensuring the integrity of data that is replicated or partitioned across servers, Microsoft SQL Server makes it easy to deploy enterprise-wide applications in a distributed environment.

The programmable server has many advantages. Application development costs can be greatly reduced because server-enforced business rules and transactions can be shared across all applications. Maintenance costs can be significantly reduced because business rules and transactions only have to be modified in one place—the server—instead of in every application using them. Database reliability can be increased because data integrity is maintained independently from application programs. Database security also increases because rules and transactions, as well as database tables, are protected from unauthorized access.


Types of Data Integrity

Enforcing data integrity involves preserving the consistency and correctness of data by validating the contents of individual columns, verifying column values with respect to one another, validating data in one table as compared to another table, and verifying that a database is successfully and accurately updated for each transaction. Data integrity falls into five categories:

  • Entity integrity preserves the uniqueness of entities (rows) in a table. Entity integrity is usually enforced by using the primary key of a table but can also be enforced through unique indexes or constraints.
  • Domain integrity refers to the valid entries for a given column. Domain integrity is enforced by restricting the data type, format, or range of possible values for a column.
  • Referential integrity maintains consistency between multiple tables of a database—for example, "Don't delete customers with open orders." Referential integrity is enforced by checking the validity of data to ensure that it exists within a range of values in another table. In Microsoft SQL Server, referential integrity can be enforced declaratively, by using constraints defined with the table, or programmatically, by using database triggers and stored procedures.
  • User-defined integrity allows organization-wide business rules to also be actively enforced. SQL Server supports user-defined integrity through its programmable server architecture. Critical business rules, such as "Don't ship to a customer with a bad credit history," can be enforced easily across all applications and users.
  • Distributed data integrity maintains the consistency and accuracy of data that is replicated or partitioned across multiple databases or multiple servers. This is a key requirement for reliable, highly available, distributed systems.

Microsoft SQL Server enforces data integrity actively in the server by using methods that fully conform to the ANSI SQL-92 standard. In addition, Microsoft SQL Server provides sophisticated data integrity extensions such as user-defined data types, defaults, rules, stored procedures, and triggers. This gives developers the maximum in flexibility and power. The table below lists the SQL Server data integrity options.

Integrity type | Former options | SQL Server 6.5 options
Entity | Unique indexes | PRIMARY key UNIQUE constraint IDENTITY property Unique indexes
Domain | Data types, defaults, rules | DEFAULT constraint FOREIGN KEY constraint CHECK constraint NOT NULL constraint Data types, defaults, rules
Referential | Triggers | FOREIGN KEY constraint CHECK constraint Triggers
User-defined | Rules, triggers, and stored procedures | All column- and table-level constraints in CREATE TABLE WITH CHECK OPTION on views Rules, triggers, and stored procedures


Single-column (Domain) Integrity

Protecting the consistency of all data in a single column prevents data-entry errors. SQL Server supports several features for enforcing single-column integrity.

Data Types

Data types determine the kind of information that can be stored in the columns of database tables. A rich set of system-supplied data types is provided—including binary large object (BLOB) data types to support storage of multimedia objects in the database. SQL Server also supports international languages with alternate sort orders and alternate date, money, and number formats.

User-defined Data Types

Developers can also define their own data types to supplement the system-supplied data types. For example, us_state_type can be defined as a two-character data type to store the legal abbreviations for each of the fifty states in the United States of America. The advantage of user-defined data types is that definitions of NULL values, defaults, and rules can be shared across many applications or tailored to specific applications. They also ensure consistency of data so tables can be joined together during transactions and queries.

Column-level and Table-level Constraints

Constraints conform to the ANSI standard for creating and altering tables. Constraints limit the possible values that users can enter into a column or columns. Multiple constraints can be associated with a single column (column-level constraint), and a constraint can be associated with multiple columns (table-level constraint). Constraints are defined when creating tables in SQL Enterprise Manager or with the CREATE TABLE statement. SQL Server provides CHECK, DEFAULT, FOREIGN KEY, PRIMARY KEY, and UNIQUE constraints.

NULL Values

SQL Server correctly distinguishes NULLs (non-entries) from any specific entry, including "0" for a number field or spaces for a character field.

Defaults

Defaults allow developers to specify a value when no value is explicitly entered for a specific column. For example, if a user does not enter a value in the order_date column, SQL Server can automatically insert the current date.

Rules

Rules specify the domain of valid values for a specific column. They can specify a set of values, a range of values, or a format. For example, the us_state_code column can be restricted to the legal abbreviation of each of the fifty states in the United States of America.

The definition of a rule can contain any expression that is valid in an SQL WHERE clause, except that it cannot refer to column or table names. It can include arithmetic operators, relational operators, LIKE, BETWEEN, and so on. The same rule can be bound to more than one column or user-defined data type, and applications automatically use any rules that have been defined. Rules can be changed or dropped at any time.

Note CHECK constraints, which specify data values that are acceptable in a column, can often be more powerful than rules. You can apply CHECK constraints to multiple columns, and you can apply multiple CHECK constraints to a single column.


Multicolumn and Multitable Integrity

SQL Server also supports features to enforce complex business rules, including referential integrity. Referential integrity is the process of preserving defined relationships between tables when you enter or delete records in those tables. Referential integrity maintains consistency between the primary and foreign keys in tables, as in "Don't delete customers with open orders." Complex business rules also involve relationships among multiple columns—often in multiple database tables—that must be enforced across all applications and users.

Declarative Referential Integrity

SQL Server provides full support for declarative referential integrity (DRI) as defined by the ANSI SQL-92 standard. DRI allows the database administrator (DBA) to define data integrity restrictions for a table as well as the relationship between tables, both of which are enforced by SQL Server automatically. DRI preserves the defined relationships between tables when records are inserted, updated, or deleted. DRI is based on FOREIGN KEY, PRIMARY KEY, or UNIQUE constraint relationships, and it automatically ensures that related key values are consistent.

Views with Check Option

Microsoft SQL Server supports WITH CHECK OPTION on views, which ensures that users query and modify only the data visible through the view. This option forces all data modification statements executed against the view to adhere to the criteria set within the SELECT statement defining the view. Combined with the appropriate security privileges, WITH CHECK OPTION provides a powerful way to ensure that specific users update only appropriate subsets of data.

Stored Procedures

Stored procedures are collections of SQL or C language statements that are precompiled and stored at the server. Developers can code complex queries and transactions into stored procedures and then invoke them directly from client applications or other servers over the network. In addition to offering performance benefits, stored procedures can be used to enforce organization-wide data integrity and business policies by ensuring that all updates occur in consistent and prescribed ways. Consider a funds transfer transaction: You can code the account credit and debit operations as well as the safety check logic. For example, you could make sure that the amount of money in the source account is greater then the amount to be transferred—by coding a single stored procedure called transfer_funds. The application would execute this stored procedure each time a funds transfer transaction occurs.

In combination with SQL Server advanced security, stored procedures offer particularly powerful ways to enforce data integrity in mixed application environments. For example, SQL Server can prevent users from doing ad hoc UPDATE, INSERT, and DELETE operations on tables, yet allow these operations to occur when they are part of a predefined stored procedure. This allows the system administrator to control exactly when and how data is changed for each user or group of users in the database.

Triggers

SQL Server centrally enforces complex business rules with a type of stored procedure called a trigger. Whereas stored procedures must be called explicitly to be executed, triggers are automatically invoked, or triggered, by an attempt to insert, delete, or update a data field. By directly monitoring changes in the data, triggers implement "data-driven integrity" as opposed to "application-driven integrity."

Triggers prevent incorrect, unauthorized, or inconsistent changes to data. Triggers accomplish this by performing any number of actions whenever a specified change to a data object is attempted. Triggers can be nested and can cascade a change throughout related tables in a database, rollback transactions, issue messages to an online user, and post alerts to the Windows NT system-wide event log.

A key advantage of triggers is that they're automatic. They work no matter what caused the data modifications: a clerk's entry, a report calculation, or a front-end application's computations. Triggers are stored in the SQL Server data dictionary, eliminating the need for redundant integrity code in applications.


Distributed Data Integrity

Distributed data integrity maintains the consistency and accuracy of data that is replicated or partitioned across multiple servers, a key requirement for reliable distributed systems. Microsoft SQL Server provides key features for ensuring distributed data integrity.

Transaction-based Replication

Microsoft SQL Server's built-in data replication enables organizations to maintain system-managed copies of business-critical information across multiple server systems. By maintaining redundant copies of critical information, replication provides for high availability in case of system failure, ensuring continuous access to critical information even if a central computing facility is unavailable.

Because Microsoft SQL Server replicates data under transaction control, the integrity and consistency of data is guaranteed. SQL Server ensures integrity for replicated data with automated synchronization and recovery capabilities. In addition, Microsoft SQL Server supports optional encryption of the data stream to provide the highest level of security between distributed locations.

Automated Synchronization

In demanding distributed-computing environments, a database server must ensure that the data being replicated between publishers and subscribers is accurate and consistent. Before data can be replicated effectively across servers, the servers must contain the same initial schema and data. The process of accomplishing this is called synchronization. Synchronization ensures that the table schema and the table data in the publisher and subscriber databases are identical and consistent with one another prior to enabling replication.

Unlike other database systems (which require the data to be synchronized manually), Microsoft SQL Server provides automatic synchronization. SQL Server takes a snapshot of the table schema and data, then automatically transfers that snapshot to subscribing servers. System administrators can select from a variety of transfer methods depending on configuration.

Constraints for Replication

Preserving the update integrity of replicated data across servers is a key requirement of replicated databases. Data at the subscribing server must be identical to the primary copy of the data at the publishing server. To ensure this, most organizations require that modifications to replicated data be made on the primary server (the "owner" of the data), and not on the subscribing servers, each of which receives exact copies of the publishing server's data. This policy prevents potential data loss and inconsistencies due to conflicts and lost updates.

Microsoft SQL Server uniquely supports this key requirement with constraints for replication, an extension to ANSI SQL that allows the use of CHECK constraints to protect the integrity of replicated data. This extension is used to protect horizontally partitioned tables that receive "source" data from another server from unauthorized data modifications to the replicated data. In this way, organizations can ensure that valid updates occur only on the server that "owns" the original copy of the data. Constraints for replication are applied to both "before" and "after" images of updated records to prevent records from being added to or deleted from the replicated range. All deletes and inserts are checked; if they fall within the replicated range, they are rejected.

Microsoft SQL Server is the only DBMS at the time of this writing to provide an automated constraint mechanism to enforce update integrity of replicated data; other systems either do not support this or require this logic to be coded into triggers, which can be a complex and error-prone approach.


SQL Server Scalability on Windows NT Server

Microsoft SQL Server on Windows NT Server—designed to grow with your organization.

Downsizing computer systems to client/server computing is widely discussed. Yet many successful companies face the opposite problem: they are upsizing their client/server applications. Because every Internet and intranet user is a potential client, applications face huge user and transaction loads. With the price of disk storage at $100 per gigabyte (GB), application systems are being required to store huge online databases.

Scalable systems solve the upsizing problem by offering you a way to increase the size and power of the network, servers, database, and applications by merely adding more hardware. Scalable computer systems provide a means by which an application's client base, database, and throughput can be increased without application reprogramming. The scaled-up server should be as easy to manage as the smaller system—at least on a per-user basis.

Traditionally, most scale up has been accomplished through symmetric multiprocessing (SMP): adding more processors, memory, disks, and network cards to a single server. Several vendors have shown that SMP servers can offer a tenfold scale up over uniprocessor systems on commercial workloads.

However, at some point, a single node hits a bottleneck, evidenced by diminishing returns or prohibitively expensive hardware. To grow much beyond a factor of ten, application designers have gravitated to a cluster architecture in which the workload and database are partitioned among an array of networks, processors, memories, and database systems. All the truly large systems are built this way. The IBM MVS Sysplex, the DEC VMScluster, the Teradata DBC 1024, and the Tandem Himalaya series are all clustered systems. Ideally, this partitioning is transparent to the clients and to the application. The cluster is programmed and managed as a single system, but it is in fact an array of nodes.

Cluster technology fits together with and leverages distributed-system technologies like replication, remote procedure call, distributed systems management, distributed security, and distributed transactions. The cluster approach has two advantages over increasingly larger SMP systems:

  • Clusters can be built from commodity components and can grow in small increments.
  • The relative independence of cluster nodes gives a natural failover and high-availability design.


SMP and Clusters

Microsoft Windows NT Server and Microsoft SQL Server support both SMP and cluster architectures. SQL Server delivers impressive peak performance for both client/server and data warehouse applications.


SMP

Microsoft SQL Server and Microsoft Windows NT Server run on 2-way to 32-way SMP hardware systems. The most common SMP hardware systems are 2-way and 4-way. Microsoft SQL Server has demonstrated excellent SMP scalability, both on audited benchmarks and in real applications.

Microsoft SQL Server scalability, version 6.5
Technologies | Active users | Throughput | Database size
SMP, failover, parallel query, distributed transactions, SQL Enterprise Manager | 5,000 per SMP | 3,600 transactions per minute 10 million transactions per day | 200 GB

Today, a single 4-processor node can support up to 5,000 concurrent users accessing a Microsoft SQL Server storing billions of records on a 200 GB disk array. These servers are capable of processing more than 10 million business transactions per day. In the future, the combination of faster processors, more processors, and software improvements could more than double the rated performance of Microsoft SQL Server on SMP hardware systems.


Clusters

Windows NT Server offers many cluster-wide services: security, naming, performance monitor, software asset management (SMS), transactions (MS DTC), distributed objects (DCOM), node and resource failover, and automatic IP address assignment (DHCP). Companies like Compaq, Digital Equipment Corporation, Hewlett Packard, Intel, NCR, Tandem, and SGI are building on Windows NT Server and are working with Microsoft to make Windows NT Server clusters even more powerful. Many additional services are planned, including an industry-standard, cluster application programming interface (API).


Clusters and Failover

Microsoft SQL Server is an early user of Windows NT clusters for failover support. Microsoft SQL Server 6.5, in cooperation with various hardware vendors, supports high-availability databases by using failover from one node to another. Microsoft SQL Server also adds support for OLE Transactions through the Microsoft Distributed Transaction Coordinator (MS DTC). OLE Transactions allow Microsoft SQL Server databases to be partitioned among multiple Windows NT Servers. MS DTC automatically manages the work of transactions that span these nodes. In addition, SQL Enterprise Manager allows an operator to monitor and manage multiple SQL Servers from a single console.


Scalability Growth

As organizations grow and acquire more and more data, they must deal with increased transaction workloads and larger databases. Each major increment presents new challenges.

Scalability includes several kinds of growth:

  • User population and network—If the user population doubles, the network and database workload probably does too.
  • Database size—With databases commonly reaching hundreds of gigabytes, operations, such as backup, restore, and load, can all become bottlenecks.
  • Transaction complexity—Application designers are building more intelligence into applications, relieving users of tedious tasks. Increasingly, applications are used for data mining and data analysis.
  • Applications—As applications become easier and less expensive to build, organizations are using computers in new ways. These new applications increase the load on existing databases and servers.
  • Numbers of servers—Clustered and distributed applications involve many nodes. Scalable systems allow a large number of nodes to be easily managed from a single location.


Scale Up and Speed Up

An ideal system improves linearly; that is, if you double the number of processors and disks, throughput doubles (linear scale up) or response time is cut in half (linear speedup). Linear scaling is rarely achieved in practice because it requires that all aspects of the system be perfectly scalable. The overall architecture includes hardware, operating system, database and network software, and the application software.

It is tempting to simplify scalability to a single metric like the number of processors a system can support. Many database applications are very I/O-intensive; however, adding CPUs to an I/O-bound system will not make it faster. Microsoft SQL Server running on today's typical 4-processor servers can achieve performance comparable to systems running on hardware with 20 processors! Is the second system more scalable because it requires 20 CPUs to achieve the same throughput? Obviously not.

The best metric is how well the system scales for your application, which is impossible to know in advance. However, you can estimate scalability by examining standard benchmarks and by looking at applications in related industries.


Scalability and Manageability

Performance is only a small part of the cost of ownership. System management and operation is often more expensive than the hardware and software. Larger systems can be difficult to design, program, administer, and operate. The following issues are important for small systems, but they become very important when the systems scale up:

Manageability—A scalable system should automate periodic and repetitive system management tasks. Operators should only be involved in exception situations that require administrative decisions.

Continuous availability—The cost of downtime increases with system size. Paradoxically, larger systems have more components and are therefore more likely to break. Scalable systems must deliver continuous availability. They must allow online operations (backup, recovery, reorganization, upgrades), and must mask hardware and software failures with automatic failover to another server.

Price/performance of commodity hardware—Any solution must use cost-effective hardware platforms. Approaches based on specialized architectures are increasingly less economic.


Technology Trends Encourage Building Scalable Systems

Technology advances and the wide adoption of computing have had some surprising results. Today, commodity (Intel-based) components are the fastest and most reliable computers, networks, and storage devices. The intense competition among microprocessor vendors has created incredibly fast processing chips. Indeed, the most powerful supercomputers are built from such chips. Conventional water-cooled mainframes are moving to this higher-speed technology.

Commodity workstations and servers rival and often outstrip the performance of mainframes. The pace of change in this commodity market is so rapid that the "low end" is years ahead of the installed base of conventional mainframe and minicomputer architectures. The following illustration shows the astonishing speedup of microprocessors over time.

Commodity computer interconnects are also making extraordinary progress. Ethernet has graduated to 12 megabyte per second (MB/sec) speeds. Switched 100 MB/sec Ethernet gives a hundredfold speedup in local networks at commodity prices. Asynchronous Transfer Mode (ATM) hardware will soon be ubiquitous for both local and wide area networks. ATM offers a tenfold increase over switched Ethernet.

The entire computer industry uses the same basic 16-megabit DRAM chips that are used in personal computers. Memory prices for commodity computers are often three to ten times less than the price of the same memory for a proprietary (manufacturer-specific) computer.

In terms of performance and reliability, the best disks are 3.5-inch SCSI disks. They have doubled in capacity every year and are rated at a 50-year interval to hardware failure. Today, the 4 GB disk is standard. The following illustration shows that in 1995, a 4 GB disk cost $1,000.

This is a thousandfold improvement over disks of 15 years ago. These low prices explain why typical servers are configured with 10 GB to 100 GB of disk capacity today. Such disks cost $2,000 to $20,000.


Computer Architecture Choices

The proliferation of many processors, disks, and networks poses an architectural challenge. What hardware architecture best exploits these commodity components? No single architecture has emerged as a winner, but there is broad agreement that three generic architectures can provide scalability:

  • Shared memory
  • Shared disk
  • Shared nothing

Windows NT Server supports all these architectures and will develop in parallel with these architectures.


Symmetric Multiprocessors

Symmetric multiprocessing (SMP) systems are relatively easy to program. They also leverage the benefits of industry-standard software and hardware components. An SMP system grows by adding memory, disks, network interfaces, and multiple processors to a single shared memory as shown in the following illustration.

SMP is the most popular way to scale beyond a single processor. The SMP software model, often called the shared-memory model, runs a single copy of the operating system with application processes running as if they were on a single processor system. Microsoft Windows NT Server and Microsoft SQL Server are designed to scale well on SMP systems. They can scale to 32 nodes for some applications, but the practical requirements for general-purpose use today are:

  • 8 processors.
  • 4 GB of main memory (2 GB per application).
  • 125 disk drives configured as 25 logical disks holding 500 GB with 4 GB disks or 1 terabyte with 8 GB disks.
  • 5,000 active clients accessing a SQL Server.

Typical large servers are half this size or less.


SMP Scalability

SMP is by far the most popular parallel hardware architecture. SMP servers based on industry-standard Intel and Alpha AXP microprocessors deliver astonishing performance and price/performance for database platforms. Intel markets a four-way SMP board based on the Pentium Pro (P6) processor. Almost every hardware vendor is incorporating this SMP board into the servers they manufacture. It appears that 4xP6 SMP servers will be the workhorse of client/server computing for the next few years.

As microprocessor speeds increase, SMP systems become increasingly expensive to build. To scale from 1 processor to 4 processors is fairly inexpensive; however, going from 4 to 8 processors in an SMP system is comparatively expensive. Beyond 8 processors, prices rise steeply, and the returns diminish.

For example, as can be seen in the following table, Compaq can deliver astonishing performance on a standard, widely available 4-processor SMP computer. It is designed using commodity hardware and delivers cost-effective database support. A 16-processor computer, designed for that same 133 MHz Pentium chip, delivers only 50 percent more performance, at over 4 times the cost.

Diminishing returns on SMP performance
Database | Hardware | CPUs | tpmC | $/tpmC | System cost
Microsoft SQL Server 6.5 | Compaq Proliant 4500/133 | 4 Pentium 133 MHz | 3,643 | $148 | $537,508
Oracle Enterprise Server, release 7.3.2 | NCR WorldMark 5100S c/s | 16 Pentium 133 MHz | 5,607 | $394 | $2,206,688

At the software level, multiple processors concurrently accessing shared resources must be serialized. This serialization limits the practical scalability for individual applications in shared-memory SMP systems. These software bottlenecks in operating systems, database systems, and applications are as significant as the hardware limitations.

Nonetheless, SMP systems are the most common form of scalability. Intel Pentium Pro, DEC Alpha, IBM PowerPC, and SGI MIPS SMP hardware systems are powerful and inexpensive SMP nodes.

Microsoft provides excellent support of these commodity SMP hardware systems and continues to invest in this technology.


Cluster Architecture

A cluster is a set of loosely coupled, independent computer systems that behave as a single system. The nodes of a cluster can be single-processor systems, or they can be SMP hardware systems. The nodes can be connected by a commodity network or by a proprietary very-high-speed communications bus. The computers in a cluster cooperate so that clients see the cluster as if it were a single, very-high-performance, highly reliable server. Because the cluster is modular, it can be scaled incrementally and at low cost by adding servers, disks, and by networking.

Windows NT Server clusters provide horizontal growth, or scale out, allowing customers to add processing, storage, and network services to a preexisting configuration. A cluster can also be grown using super-server SMP nodes, but usually it is built with commodity components and commodity interconnects. Two interconnects are used for fault tolerance.

Cluster architectures allow you to scale up to larger than a single SMP node. When demand exceeds the ability of commodity SMP nodes, or when fault tolerance demands a second failover server, it is attractive to use multiple nodes to form a cluster.


Shared-Disk and Shared-Nothing Clusters

In a shared-disk cluster, all processors have direct access to all disks and data, but they do not share main memory. An extra layer of software called a distributed cache or lock manager is required to globally manage cache concurrency among processors. The Digital VMS cluster and Oracle Parallel Query Option are the most common examples of a shared-disk parallel database architecture. Since access to data is serialized by the lock or cache manager, the shared-disk cluster has some of the same scalability limitations as shared-memory SMP systems. The following illustration shows a shared-disk cluster.

The shared-nothing cluster architecture avoids the exotic interconnects and packaging of a scalable shared-disk cluster by connecting each disk to one or two servers. In a shared-nothing cluster, each node has its own memory and disk storage. Nodes communicate with one another by exchanging messages across a shared interconnect. Each node in a shared-nothing cluster is a free-standing computer with its own resources and operating system. Each is a unit of service and availability. Each node owns and provides services for some disks, tapes, network links, database partitions, or other resources. In case of node failure, the disks of one node may failover to an adjacent node—but at any instant, only one node is accessing the disks. The following illustration shows a shared-nothing cluster.

Proprietary shared-nothing cluster solutions have been available for several years from Tandem, Teradata, and IBM Sysplex. These solutions all depend on exotic hardware and software and are therefore expensive.

Microsoft SQL Server and Windows NT Server clusters will bring scalability and fault tolerance to the commodity marketplace. Microsoft is building clustering technology directly into the Windows NT Server operating system. This technology will work well with commodity servers and interconnects—and it will be able to leverage special hardware accelerators from vendors like Compaq, Digital, and Tandem. Microsoft BackOffice products such as Microsoft SQL Server, Microsoft Internet Information Server (IIS), and Microsoft Exchange Server, will be enhanced to take advantage of this clustering support. Many third-party products are also being ported to this architecture.


Kinds of Parallelism

Software and applications running on an SMP or cluster system must use parallelism to benefit from the many disks and processors that these scalable architectures provide.

There are two generic kinds of parallelism:

  • Pipeline parallelism breaks a task into a sequence of steps. The result of one step is passed to the next step. An industrial assembly line is an example of pipeline parallelism.
  • Partition parallelism breaks a big task into many, little, independent tasks that can be done in parallel. Multiple combines harvesting grain from several fields is an example of partition parallelism.

The following diagram illustrates pipeline and partition parallelism.

Microsoft SQL Server provides a good example of both partition and pipeline parallelism when reading disks. By striping data across many disks, each disk can deliver a part of a large data read—that is partition parallelism. Microsoft SQL Server uses pipeline parallelism by issuing prefetch reads to the disks with one task, processing the data with another task, and passing it back to the application task.


Parallel Processing

Windows NT Server was designed for SMP hardware systems. Windows NT Server is a fully threaded operating system that provides a rich set of synchronization primitives. The shrink-wrapped version of Windows NT Server is enabled for 4-way SMP. Larger SMP hardware systems are not yet a commodity product, so their operating system is generally packaged with the hardware. Companies like Digital, Intergraph, NCR, Sequent, and SGI, which build 8-way and 32-way Windows NT Server multiprocessors, modify Windows NT Server for their hardware and ship it with the hardware package.


Parallel I/O

Windows NT Server also has built-in disk partitioning. It allows logical volumes to be spread across multiple physical volumes. Each logical volume can be a RAID or it can be an individual disk. Windows NT Server has the following software support:

  • RAID 0—striping a logical volume across multiple physical volumes.
  • RAID 1—disk mirroring or shadowing in which data is replicated on multiple disks.
  • RAID 5—a fault-tolerant storage strategy in which disks are organized so that one stores parity for data on the others. RAID 5 is more space-efficient than RAID 1.

This software support lets Windows NT Server customers build reliable storage with commodity controllers and disks. RAID also offers partition parallelism since it spreads the data among multiple disks that can be read in parallel.

Windows NT Server can read individual commodity SCSI disks at their rated speed of 8 MB/sec and can drive SCSI controllers at speeds of 18 MB/sec. By using a PCI-based (peripheral component interconnect) machine and by striping data across 4 SCSI controllers, a single commodity Pentium processor running Windows NT Server has been clocked reading a disk array at 60 MB/sec. This means that a single Pentium processor can read or write data at 200 GB per hour. These rates are important for data-intensive operations like data loading, backup, data indexing, and data mining.

These are impressive numbers for any computer, but they are especially impressive when using commodity single-processor systems. By using multiple processors and multiple PCI buses, SMP systems can read and write data at even higher speeds and still have power left over to analyze and process the data.


Scalability Architecture

Microsoft SQL Server makes full use of Windows NT Server SMP capabilities: threads and the Windows NT Server scheduler. Each Windows NT Server node typically has a single Microsoft SQL Server address space managing all the SQL databases at that node. SQL Server runs as a main address space with several pools of threads. Some threads are dedicated to housekeeping tasks like logging, buffer-pool management, servicing operation requests, and monitoring the system. A second larger pool of threads performs user requests. These threads execute stored procedures or SQL statements requested by the clients. The following diagram illustrates this architecture.

Microsoft SQL Server is typically used in a client/server environment where clients on other computers connect to the server and issue either SQL requests or stored procedures usually written in the Transact-SQL language. Clients can also be located at the server node. Microsoft SQL Server uses a built-in TP-monitor utility, Open Data Services, to support large numbers of clients. In practice, this has scaled to 5,000 concurrent clients. Beyond that size, it makes sense to either partition the application into a cluster of nodes, or use another TP monitor to connect clients to SQL Server. All common TP monitors, such as CICS, Encina, Tuxedo, and Top End, have been ported to Windows NT Server and interface with Microsoft SQL Server.

Microsoft SQL Server achieves near-linear speedup on SMP machines. Many benchmarks have demonstrated this. Two notable examples are the DEC Alpha TPC-C benchmark and the Intergraph benchmark.


Clusters

Every SMP system has a maximum size: a maximum number of nodes, memory, disks, and network interfaces that can be attached to the system. To go beyond these limits, the software architecture must support a cluster.

All the largest computer systems are structured as clusters. The largest known database, the WAL-MART system, runs on an NCR/Teradata cluster of 500 Intel processors accessing approximately 1,500 disks. Other large databases are supported by IBM MVS/Sysplex systems, Tandem Himalaya systems, or Digital VMScluster systems.

Clusters work by partitioning the database and application among several different nodes, or computers. Each node stores a part of the database and each performs a part of the workload. The cluster grows by adding nodes and redistributing the storage and work to the new nodes. This growth and redistribution should be automatic and require no changes to the application.

Partitioned data is used in centralized systems to scale up capacity or bandwidth. When one disk is too small for a database, the database system partitions it over many disks. This same technique is used if traffic on a file or database exceeds the capacity of one disk. This partitioning is transparent to the application. The application accesses all data on all the disks as though it were on a single disk. Similarly, clients are partitioned among networks to scale up network bandwidth. Clusters generalize this partitioning to spread the computation among cluster nodes. The key challenge is to make this partitioning transparent to the customer, so that a cluster is as easy to manage and program as a single system.


Growing Beyond SMP Limits

Clusters have several advantages. The most obvious is that they can grow to huge sizes. By building clusters from SMP nodes, you can scale up an application by a factor of ten or a hundred. Indeed, Digital, Tandem, and Teradata have many hundred-node clusters in production today.


Commodity Components

Clusters can be built with high-volume components, which are relatively inexpensive. Relatively few high-end SMP machines are sold—relatively few customers will buy a 20-way SMP. So, 20-way SMP hardware systems are expensive because the engineering cost is amortized over relatively few units. Inexpensive clusters can be built with commodity 4-way SMP hardware systems. This means they have superior price/performance. In addition, because they are built from commodity components, commodity clusters can grow in smaller increments. You can add disks or nodes or network cards as needed rather than buy a huge new box each time you add to your system.


Availability by Using Fault Tolerance

By partitioning data and work, clusters provide firewalls that limit the scope of failures. When a node fails, the other cluster nodes continue to deliver service. By replicating data or by allowing storage and network devices to fail over to surviving nodes, the cluster can provide uninterrupted service.

Commodity SMP hardware systems are logical building blocks for clusters. Availability, scalability, and economics demand that large systems be built as arrays of these commodity components. SMP hardware systems provide vertical growth of nodes from single-processor systems to large SMP hardware systems. Clusters provide horizontal growth by combining these SMP hardware systems into Windows NT Server clusters.


Distributed Systems Techniques

Distributed systems techniques are key to building transparency into clusters. By structuring applications and systems as modules that interact by using remote procedure calls, applications become more modular and can be distributed among nodes of the cluster. The client calls upon a service by name. The procedure call either invokes the service locally or uses a remote procedure call if the service is remote.

Microsoft has invested heavily in structuring its software as components that interact by using remote procedure calls. The resulting infrastructure goes by the following names:

  • OLE—object linking and embedding
  • COM—component object model
  • DCOM—distributed COM

Many aspects of the COM are in place today. In particular, with Windows NT Server 4.0 and Microsoft SQL Server 6.5, Microsoft delivered:

  • DCOM—distributed creation of objects in a network based on remote procedure calls.
  • OLE Transactions (also called Microsoft Distributed Transaction Coordinator)—distributed transactions that allow applications to do work at many Microsoft SQL Server database partitions and automatically (transparently) get the ACID distributed transaction semantics (atomicity, consistency, isolation, and durability).

Windows NT Server supports these features along with many other cluster facilities including cluster security (domains), cluster software management (SMS), cluster naming (distributed name service), and cluster performance monitor (Perfmon). Microsoft SQL Server complements these facilities with management tools built into SQL Enterprise Manager that allow it to manage and monitor an array of Microsoft SQL Servers.


Database Failover

Microsoft SQL Server 6.5 offers fault-tolerance and high availability by providing failover from one server to another when the first server fails or needs to be taken out of service for maintenance.

The failover mechanism works as follows: Two Windows NT Servers can be configured as dual servers. The pair must have shared access to a SQL Server database stored on shared disks. One of the Microsoft SQL Servers is the primary server. It accepts requests from clients and both reads from and writes to the database. The following illustration shows the primary and secondary server setup before a failure on server one.

The other Microsoft SQL Server node (the failover) can provide access to other databases, but it is not accessing the database being managed by the primary server. The following illustration shows the secondary server taking over after a failure on the primary server.

If the primary server fails, Windows NT Server at the failover server takes ownership of the disks holding the database. It informs the failover server that it is now the primary server. The failover server recovers the database and begins accepting client connections. For their part, clients connect to the failover server when the primary server fails.

The dual-server failover is completely automatic. The whole process of detecting and recovering from failure takes only a few minutes. When the primary server is repaired, it is restarted and either becomes the new failover server, or assumes primary server responsibilities again.


Microsoft SQL Server and Windows NT Server Manageability

It is relatively easy to build huge systems. Microsoft provides easy installation of the operating system and database using graphical tools and wizards. SQL Server also includes wizards to set up database management.

However, because these systems involve thousands of client systems and huge databases, manageability is a real challenge. Managing and operating a computer system has always been a major part of the cost-of-ownership. When hardware and software prices plummet, the residual management cost becomes even more significant. Loading, dumping, and reorganizing 100 GB databases is a challenge. At the 3 MB/sec data rate of most tape drives, it takes a day and a half just to dump a 100 GB database with one tape drive. Defining and managing the security attributes of 5,000 different users is a daunting task. Configuring the hardware and software for 5,000 clients is another time-consuming task.


Scalable Windows NT Server Management

Managing the software and hardware configurations of thousands of clients is probably the most challenging task of operating large client/server systems. Windows NT Server and Microsoft System Management Server automate many of these tasks.

Windows NT Server security provides a domain concept and a single logon password for each application running on Windows NT Server. Windows NT Server security also provides user groups. Large user populations can be managed by authorizing groups and adding users to groups. The Windows NT Server security mechanism works as a collection of security servers (domain controllers) spread among the network nodes. This distribution provides both scalability and availability. Individual domains have been scaled to over 40,000 users. Windows NT Server security scales beyond that size by partitioning into a multidomain architecture with trust relationships among domains. The security system has both a programmatic and an intuitive graphical interface that allows any node to manage the network security.

Microsoft System Management Server (SMS) allows a single system administrator to manage the software configuration, licensing, and upgrades of tens of thousands of clients. SMS automates most tasks and minimizes exception situations that require an expert. To give another example, Windows NT Server DHCP protocol automatically assigns TCP/IP addresses to nodes on demand, eliminating time-consuming and error-prone tasks, allowing node mobility, and conserving the address pool.

Windows NT Server has built-in tools to log errors, manage disk space, set priorities, and monitor system performance. All these tools can manage a cluster of client and server nodes. The following illustration shows the performance monitor at one node tracking the CPU and network use of several nodes.

Each Windows NT Server node has over 500 performance counters for its internal behavior. Microsoft SQL Server, Microsoft Exchange Server, and many other products ported to Windows NT Server integrate with this performance monitor. Microsoft SQL Server adds over 75 performance counters to this and integrates with the Windows NT Server event log to announce events.


Scalable Microsoft SQL Server Management

SQL Enterprise Manager is a breakthrough in managing database servers. It gives administrators a visual way to manage and operate many SQL systems from a single console.

The graphical interface has several built-in wizards to help set up and automate standard tasks. The key features of SQL Enterprise Manager are:

  • A fully graphical administration interface to control and monitor the operation of many Microsoft SQL Servers and the clients accessing them.
  • A job scheduler that runs periodic administrative tasks such as dumps, reorganizations, and integrity checks.
  • A Distributed Management Objects (DMO) mechanism that allows administrators to automate exception handling and to automate tasks by writing Visual Basic® scripts or by letting a wizard write the script. These procedures can use e-mail and a TAPI-based beeper system to report results or notify operators when their attention is needed.
  • An extension mechanism that allows third parties to add new administrative tools.
  • A fully graphical interface to configure and manage database replication.

SQL Enterprise Manager includes the Database Maintenance Wizard to set up routine maintenance operations and the Web Assistant to routinely publish Web pages from the database to an Internet or intranet.

Utilities to load, dump, recover, check, and reorganize large databases are key to operating a system with huge databases. Backing up a 100 GB database using a single high-performance tape drive will take over 33 hours. By using multiple disks and tapes in parallel, Microsoft SQL Server and Windows NT Server have shown a sustained dump rate of 20 GB per hour. This benchmark was I/O-limited; with more tapes and disks, the dump rate could have been even faster. Management of the dumps can be controlled by the SQL Enterprise Manager job scheduler working with commodity tape robots. These dumps can either be done at full-speed or in the background at a slower rate. By doing incremental dumps and by increasing the degree of parallelism, huge databases can be dumped in a few hours.


Publishing Data on the Internet

Integrating Microsoft SQL Server with your Internet site or intranet ensures an active, robust Web presence.

Thousands of companies are discovering the potential of internal corporate networks as logical and powerful extensions of their external publication platforms. Microsoft SQL Server enables organizations of all sizes to employ the power of this technology to the greatest possible advantage. By integrating SQL Server with your Internet or intranet site, you can build an active, robust Web presence by publishing real-time information, providing for interaction and customization, and conducting business securely and reliably—all with confidence in the integrity of your data. This article discusses:

  • Databases on the Web.
  • SQL Server and the active Internet.
  • Optimizing SQL Server for the active Internet.

The Internet has introduced new technologies associated with global communications and wide-area public networks. Microsoft's strategy is to work openly with customers, other companies, and industry groups to realize the full potential of the Internet. The next generation of powerful Internet applications promises to make the Internet more exciting and useful by seamlessly integrating audio, video, three-dimensional animation, and more.

Microsoft's strategies for supporting business on the active Internet are shown in the following table.

Strategy | Supporting software
To provide the network foundation for distributed computing | Windows NT Server operating system
To provide a family of integrated server applications | Microsoft BackOffice family of products
To provide distributed object and systems technology | Microsoft Win32® application programming interface OLE
To provide a complete set of development and authoring tools | Microsoft Visual Basic programming system Java Microsoft JScript™ development software Microsoft FrontPage™ Web authoring and management tool Microsoft Visual InterDev™ Web development system
To provide a set of desktop applications | Microsoft Office
To provide operating systems that take advantage of all the above features | Microsoft Windows® 95 operating system Windows NT Workstation operating system


Databases on the Web

Many organizations have already realized the benefits of the Internet as a means of rapidly publishing information. Companies today are using the World Wide Web primarily as an electronic storefront, billboard, or yellow pages ad. Many have applied these same principles to internal communication, establishing intranets to exchange mission-critical information across local, regional, and even global enterprises. Until recently, this information has been predominantly static, preformatted HTML documents, not interactive, user-centric applications.

The Internet is becoming a more dynamic and interactive environment. Whether in traditional distributed computing or on the Internet, businesses and users need to access and manage an ever-expanding amount of information, from anywhere, at anytime.

By connecting Internet or intranet Web servers to relational databases like Microsoft SQL Server, many organizations have moved beyond static document publication to an active Internet, where content is generated dynamically from a database, automatically, or in response to a user request. An active Internet application can use electronic forms to collect orders, customer information, and other transactions, then store them in a relational database. The database, in turn, allows processing, retrieval, and analysis with a variety of off-the-shelf tools. An active Internet can store information in a single, secure place—without duplication—regardless of whether that information is accessed internally or over the Web.

To allow secure business transactions to occur over the Internet, companies are building a new class of active Internet business applications, based on products like Microsoft Internet Information Server, Microsoft SQL Server, and the BackOffice family of products.


SQL Server and the Active Internet

The active Internet is a new type of distributed client/server environment that extends beyond traditional corporate information technology boundaries. A major requirement for an active Internet is a secure, reliable, and scalable place to store information. Microsoft SQL Server is built from the ground up as a scalable, high-performance database management system designed specifically for the unique requirements of distributed client/server computing. SQL Server has been fulfilling this role in business environments for several years.

As Internets and intranets become more complex and more heavily trafficked, managing incoming and outgoing information becomes even more difficult. By applying basic distributed computing and client/server principles to this new frontier, companies can reduce the risk and the complexity of doing business on the Internet. Integrating Microsoft SQL Server with an Internet or intranet allows organizations to:

  • Build active Web sites, capturing the user's interest by publishing real-time information and providing user interaction and customization.
  • Conduct business on the Internet, securely and reliably.
  • Develop corporate intranets, giving users new tools to access business information, without compromising security and data integrity.


Building Active Web Sites

As businesses explore new ways to leverage the Internet for business operations, they have been quick to recognize that most of the business content they would like to publish is already being managed by a relational database management system. These businesses also realize that today's Web sites are measured not just on content, but on presentation and level of interaction. The more popular sites capture the Web user's interest by publishing real-time information and building customized pages. These sites put users in control, allowing them to browse large volumes of data and provide input. A client/server database like Microsoft SQL Server is needed to accomplish this.

Ethos Corporation, for example, is an interactive service provider delivering up-to-the-minute financial news and research information to more than 300,000 online investors weekly. Their Web site InvestorsEdge, http://www.investorsedge.com, is among the most active financial services sites on the Internet, offering online stock quotes, corporate summaries, financial news, and personal portfolio analysis. Microsoft SQL Server drives this site, collecting, managing, and publishing the real-time financial data—averaging 3.4 million transactions per day.

Personal portfolio analysis brings a new level of customization to the InvestorsEdge Web site, allowing each user to build an individual portfolio of 15 stocks to be tracked over time. Once established, a portfolio can be accessed only with a unique user ID and password combination, where the user views a completely personalized Web page displaying the performance history of their stocks. This sensitive information is protected by Windows NT Server and SQL Server integrated security.


Conducting Business on the Internet

Many organizations are already realizing the benefits of connecting existing business systems to the Internet. By automating the communication and processes between customers and suppliers, businesses become more efficient. However, electronic commerce is progressing more slowly than expected. Fewer than 10 percent of Internet users make regular online purchases. The biggest deterrents to conducting business on the Internet are data integrity and security.

Security on the Internet is vital for both extending the enterprise and conducting electronic commerce. The industry has focused on defining technologies and industry standards to secure the communications between Web servers and browsers. Technologies and standards include encryption, secure transaction, user authentication, and signed-code or digital signatures. Microsoft and its partners have participated in the development of several important new technology standards, including Secure Sockets Layer (SSL), a secure protocol providing data encryption, server authentication, and message integrity for a TCP/IP connection, and Secure Electronic Transactions (SET), a technical standard for safeguarding payment-card purchases made over open networks like the Internet.

While these are critical components in providing a secure environment for conducting business on the Internet, they only address part of the security problem. Looking at traditional client/server environments gives insight into other security issues. Controlling user or application access to information is a fundamental security requirement of any business application. Data and transaction integrity are also critical in any multiuser business environment, ensuring that all transactions are either fully completed or are rolled back so that every user's view of data is consistent and reliable.

These security and integrity issues were solved for traditional business applications years ago by Microsoft SQL Server technologies like user and application security, data integrity and concurrency controls, datastream encryption, data replication, and transparent distributed transactions. Solving these issues for the Internet doesn't require new technology. Applying SQL Server technology to the Internet gives you proven solutions to the challenges of data security and integrity.

Controlling User and Application Security

Both Internet and intranet servers need to augment anonymous user control with specific per-user and per-group access control. Both Microsoft Internet Information Server and Microsoft SQL Server build on the Windows NT Server security model to deliver Internet-specific security features like control over anonymous access, network- or host-based access, and secure Internet authentication.

Consider a group of intranet users who have been given access to a particular Web site. With client authentication, users can identify themselves to Internet Information Server and gain access to those directories and files marked as readable only by the group. Because the user-accounts database of Windows NT Server is full-featured, any number of overlapping groups can be created and granted differing access to resources on the server. Taking this a step further—if they're authenticated by Windows NT server, they are also authenticated to SQL Server so you don't have to maintain multiple security databases.

Replicating Rich Text and Graphical Content

Microsoft SQL Server replication answers the traditional client/server challenge of distributing and synchronizing information throughout an organization, while guaranteeing integrity and reliability. Replication solves a similar set of problems for Internet and intranet sites—allowing Webmasters to manage and synchronize multiple copies of published information. Replication also allows an organization to avoid exposing sensitive database information on an intranet by selectively replicating data from production SQL Servers to a Web-connected SQL Server. SQL Server 6.5 can replicate complex text and image data popular on Web sites.

Integrating Legacy Systems

Most medium-to-large companies today have significant investments in their information systems infrastructure. Information is stored in a variety of different and often incompatible database management systems. The vast majority of these legacy systems provide no integration with the Internet. With Microsoft SQL Server–compatible middleware solutions like Microsoft TransAccess® or Information Builders EDA/Open Database Gateway, customers can integrate data across the enterprise onto the Internet.


Developing Corporate Intranets

Intranets let colleagues work together whether they're around the corner or around the globe. While exact figures are hard to come by, industry analysts estimate intranet Web sites outnumber Internet Web sites ten-to-one—an amazing growth rate considering there were no intranets three years ago!

To support this shift, Microsoft is making internal business use of the active Internet a key strategic focus. For example, on the desktop, Microsoft is making Windows clients (Windows 95 and Windows NT Workstation) the best active Internet clients by designing Internet capabilities into the operating systems themselves. Microsoft has enhanced Office—the leading choice in business productivity software—so that Office tools serve as Web creation tools. Microsoft has also offered free viewers, which let users read Office documents, even if they don't have Office installed on their local PCs. Microsoft has integrated the Web protocols TCP/IP and HTTP into its Windows NT Server platform, allowing Internet users to share, search, and use Web pages and documents the same way they use files and applications on a LAN. With SQL Server 6.5, Microsoft is extending its industry-leading distributed client/server database to be the best engine for corporate intranet applications.

Business applications on corporate intranets have the same requirements for security and integrity as their Internet counterparts. Organizations developing and deploying intranet applications are benefiting from the same proven technologies—user and application security, data integrity and concurrency controls, datastream encryption, data replication, and transparent distributed transactions technologies—that make Microsoft SQL Server the best platform for conducting business on the Internet.


Optimizing SQL Server for the Active Internet

From its foundation of superior performance, reliability, and scalability to its tight integration with Microsoft Internet Information Server and the other BackOffice products, SQL Server is unquestionably the best database platform for the new breed of Internet applications. Microsoft SQL Server 6.5 builds on this success by introducing a number of tools and technologies that provide significant advantages over alternative solutions:

  • Fast and easy programming interface
  • Open Internet database connectivity
  • Automated Web publishing of database information
  • Cost-effective licensing


Fast and Easy Programming Interface

Traditionally, Common Gateway Interface (CGI) scripts have been used to add functionality (like linking forms with an SQL database) to standard HTML forms. Each field on an HTML form can require up to 25 lines of CGI script to link it with a database. This model requires a high level of up-front programming. Any modifications are extremely labor intensive, given the one-to-one correspondence between the form field and the CGI script. The lack of quality database connectivity tools is partially responsible for the slow migration of commercial and business applications to the Internet.

Microsoft has developed Internet Server APIs (ISAPIs) like Active Server Pages (ASP), Internet Database Connector (IDC), and dbWeb to counter inefficient CGI technology. When your Web server needs to process more than one transaction per minute, CGI applications have been proven to degrade performance.

IDC and SQL Server Web Assistant can be used together to integrate SQL Server with the Web.

The following illustration shows how IDC and the SQL Server Web Assistant enable seamless connectivity with SQL Server data. IDC, or the pull model, allows a Web user to initiate dynamic, user-driven queries to a SQL Server from within an HTML document. The SQL Server retrieves or updates information in a database. The SQL Server Web Assistant, or push model, allows a database administrator or Webmaster to define a set of data (a query or stored procedure) that is automatically merged into an HTML document either on a scheduled basis or when the data changes.


Open Internet Database Connectivity

IDC is an ISAPI that uses Open Database Connectivity (ODBC) APIs to move information between SQL Server and the Internet. IDC provides the ability to create direct links between fields on HTML forms and SQL Server data without the need for complicated CGI scripts. Organizations are already using IDC to:

  • Publish real-time database information to the active Internet.
  • Capture and store gigabytes of information directly to SQL Server.
  • Perform high-performance searches of online SQL Server data.
  • Build a new class of active Internet commercial and business applications.

Conceptually, database access is performed by Internet Information Server (IIS) as shown in the following illustration.

Internet Database Connector

IDC uses two types of files to control how the database is accessed and how the output Web page is constructed. These files are Internet Database Connector (.idc) files and HTML extension (.htx) files.

IDC files contain the necessary information to connect to the desired ODBC data source and execute the SQL statement. An IDC file also contains the name and location of the HTML extension file.

The HTML extension file is the template for the actual HTML document that will be returned to the Web browser after the database information has been merged into it. This allows static text, graphic images, or even real-time video to be combined with database information on the same Web page.

IDC is ideal for building active Internet applications that allow the user to view and update information in a database. Applications for event registration, loan application processing, online banking, and other uses can be created by using this technology.


Automated Web Publishing of Database Information

SQL Server Web Assistant, one of the new Internet extensions available in SQL Server 6.5, provides the ability to easily and automatically generate Web pages formatted in HTML. Used in conjunction with an appropriate Web server product, the Web Assistant publishes Microsoft SQL Server–based information from anywhere in an organization.

The Web Assistant uses a step by step, wizard-like interface that walks a DBA or Webmaster through the process of creating a query, formatting output, and scheduling the query execution, making it easy for customers to create interactive, database-driven Web sites with automated information content. Using a data "push" model, the Web Assistant automatically publishes information out of a SQL Server database directly to the Web page. The data can be updated automatically: on a regularly scheduled basis or whenever relevant data changes. The data remains accessible to any existing client/server application as well as to the Web.

The Web Assistant is particularly valuable when publishing large amounts of database information that will be the same for all visitors to a Web site, such as price lists, inventory, or online catalogs. The Web Assistant is helpful in publishing time-sensitive or dynamic data that users need to view in real-time, like stock quote information. The Web Assistant is resource-efficient, executing the query only once, regardless of how many people visit the page.


Cost-Effective Licensing

User-based licensing models of traditional client/server RDBMs, in which customers are charged for the number of concurrent users accessing the database, have proven unworkable for the Internet. Microsoft SQL Server Internet Connector, sold separately from Microsoft SQL Server, provides a simple, flexible, and cost-effective way for customers to license their databases for use on the Internet or corporate intranets.

Internet Connector licensing is an open solution, providing access to Microsoft SQL Server from IIS or from third-party Web servers. Internet Connector allows an unlimited number of Internet and intranet connections to a single SQL Server.

Internet Connector licensing is supported for version 6.0 and version 6.5 of Microsoft SQL Server.


Looking Ahead

Microsoft has been long engaged in strategic development for the active Internet, with the goals of making it easy for customers to get on the Internet, making it safe and reliable for significant business and consumer applications, and creating a viable business model that will support the industry and its consumers.

As a result, Microsoft is well positioned to devise and implement a comprehensive active Internet strategy to meet the needs of corporate users, consumers, content creators, software vendors, Web publishers and other information providers for a unified computing/Internet experience.

To deliver the full potential of the active Internet, Microsoft uses ActiveX™ technologies—a robust framework for creating interactive content using software components, scripts, and existing applications that can be embedded in HTML documents. Specifically, ActiveX technologies enable developers to build Web content easily by using ActiveX controls (formerly OLE controls), active scripts, and active documents.

The ActiveX server framework allows developers to create the same rich, interactive applications for Microsoft BackOffice, leveraging their existing experience, knowledge, and tools. ActiveX server controls and ActiveX server scripts, written with a variety of scripting languages, like Microsoft Visual Basic Scripting Edition, PERL, and JScript, provide the building blocks for the next generation of server-driven active content. Together, these ActiveX controls and scripts make it easy for organizations to integrate Microsoft SQL Server and other BackOffice products with the Internet for building active Web sites, conducting business, and developing corporate intranets.


Part 2 - Understanding SQL Server Architecture and Components

A clear understanding of the basic structure and behavior of Microsoft SQL Server can help you optimize your SQL Server system to better accommodate your organizational database needs. Part 2 provides these articles:

  • SQL Server Architecture
  • Database Internals
  • Microsoft Distributed Transaction Coordinator


SQL Server Architecture

Microsoft SQL Server architecture, network architecture, and distributed management framework combine to simplify the management of multiple, distributed databases.


Product Architecture

SQL Server is a client/server database system. The terms client and server refer to:

  • Database client and database server software.
  • Client and server computers.

The database server software processes requests submitted by the client software, sending the results of each request back to the database client that requested it. SQL Executive and the SQL Server engine are examples of database server software.

The database client software connects to the database server software, makes requests, receives results, then manipulates those results—for example, it could display the results on the screen. SQL Enterprise Manager, ISQL/w, and Microsoft Access are good examples of database client software that connects to SQL Server databases.

The server computer runs the SQL Server database server software. The SQL Server database client software can also be run from the server computer.

Note SQL Executive, a service that runs on the server computer, is a normal database client from the perspective of the database server. A client computer is a computer that runs only the database client software.

The following illustration shows the interaction between a client computer and a server computer. The client computer, configured with Windows 95, Windows NT Server, Windows NT Workstation, Windows 3.1, or MS-DOS® operating systems, runs SQL Server client applications. This client application sends requests to the SQL Server residing on the server computer. The server computer, configured with the Windows NT Server operating system, runs all types of SQL Server applications, including client and server applications, as well as the SQL Executive service.

The database client software is made up of multiple layers, or components. The user interacts directly with a client application, like SQL Enterprise Manager or an order entry form. The client application determines the presentation of the database system. All client applications interact with SQL Server using one of two native application programming interfaces (APIs) for client database access:

  • Open Database Connectivity (ODBC)
  • DB-Library

Both ODBC and DB-Library use the same client Net-Library layer to establish a connection to SQL Server.

When the client software is running on a client computer, the connection to SQL Server is established across the network.

The database server software is also made up of multiple layers. A server Net-Library layer accepts connection from the client. Open Data Services is an API for writing database server software. The SQL Server database engine is an Open Data Services application. SQL Server communicates with the client through Open Data Services, receiving requests and returning results.

The following illustration shows the network connection from the client computer and client Net-Library to the server computer and server Net-Library.

When the client software is running on the server computer, a local, non-network connection to SQL Server can be established using named pipes. But in all other respects, the same client server architecture and components are used.

The following illustration shows this non-network connection.

Multiple client Net-Libraries are included with the SQL Server client software. The Net-Library layer is designed to "hide" the network connectivity details of communicating with SQL Server. Because all client Net-Libraries share a single interface, both the ODBC SQL Server driver and DB-Library can use any Net-Library to establish a connection to SQL Server. Client computers have a default Net-Library (usually named pipes) that is used when a specific Net-Library is not requested.

Each Net-Library (client and server) uses a single interprocess communication (IPC) mechanism, such as named pipes, remote procedure call (RPC), or Windows Sockets. The IPC used by some Net-Libraries is supported by multiple network protocols. For example, the named pipes IPC is supported by the NetBEUI, Microsoft TCP/IP, and NWLink protocols. The IPC used by other Net-Libraries is supported by a single network protocol. For example, the Windows Sockets IPC is supported only by the Microsoft TCP/IP protocol, and the NetWare IPX/SPX IPC is supported only by the NWLink protocol. Also, the named pipes IPC is also directly supported by the Windows NT file system, allowing local, non-network connections between client software and SQL Server on the same server computer.

The following illustration shows the interaction between client Net-Libraries and server Net-Libraries.

Multiple server Net-Libraries are included with the SQL Server database server software. SQL Server "listens" for client connections using multiple server Net-Libraries.

It is important to understand that the client Net-Library (and IPC) that establishes a connection must match the server Net-Library (and IPC) that accepts the connection. Of course, both the client computer and server computer must be using the same network protocol, but this alone is not sufficient. For example, a client cannot use the client TCP/IP Windows Sockets Net-Library to make a connection across the TCP/IP protocol to a SQL Server that is only using the server named pipes Net-Library. You can fix this situation in one of two ways:

  • The client can use the client named pipes Net-Library to connect across TCP/IP to a SQL Server that is only using the server named pipes Net-Library.
  • The client can use the client TCP/IP Windows Sockets Net-Library to connect across TCP/IP to a SQL Server that is using the server TCP/IP Windows Sockets Net-Library.

The following illustration shows the many options facing a database developer when choosing a set of database development tools and components.

The highest layer is the development tool or product. Two of the most common language tools are the Microsoft Visual Basic and Microsoft Visual C++® programming systems. Both of these tools offer a great deal of power and flexibility, but often require coding. Other office development tools like Microsoft Access, Word, and Excel are used to deliver customized business solutions that need data access. SQL Server includes database development and management tools like SQL Enterprise Manager and ISQL/w.

The next layer is the component. Components like Data Access Objects (DAO) and Remote Data Objects (RDO) provide a higher level of abstraction, enabling a developer to do more with less lines of code, and allowing the same code to work with multiple data sources. The SQL Distributed Management Objects (SQL-DMO) component exposes a completely programmable management interface specifically for SQL Server.

All components and tools must eventually connect to SQL Server using one of the two native APIs available today—ODBC or DB-Library. The OLE DB ODBC provider allows development of OLE DB applications that use the SQL Server ODBC driver to connect to SQL Server. An application can be written directly to a native API.

You can develop components for the server computer as well. An extended stored procedure is an Open Data Services dynamic-link library (DLL) at the server that can be called by the client like a normal stored procedure. By using the OLE Automation stored procedures, you can develop and deploy an OLE Automation object at the server that can be called by any client.

The SQL Server product contains multiple services and components, on both the client and the server computer, that interact with each other and with Windows NT services and components.

The following table lists and describes the three Windows NT services that the server computer runs under the control of the Windows NT Service Control Manager.

Service | Description
SQL Server database engine | Handles all databases, clients, and queries.
SQL Executive | Handles scheduling tasks, monitors for and raises alerts, and replicates data.
Microsoft Distributed Transaction Coordinator | Handles transactions distributed among multiple SQL Servers.

Other components, like SQL Mail, SQL Simple Network Management Protocol (SNMP), and the server component of SQL Trace are extended stored procedures. These components interact with required Windows services as well as with the SQL Server engine.

Microsoft Internet Information Server (IIS) can deliver SQL Server data to its Internet and intranet clients. IIS can connect directly to SQL Server using the Internet Database Connector (IDC), execute a query, format the results into an HTML page, and send the page to an Internet client. IIS can also deliver HTML pages that have already been created by the SQL Server Web Assistant.

The client computer runs SQL Server client applications, such as SQL Enterprise Manager, that connect to SQL Server. The client computer also runs applications included with Windows, such as Performance Monitor and Internet Explorer.

The following illustration shows how different services and extra components interact with each other and with the client and server.


Devices

Devices are normal operating files used to store SQL Server databases. Multiple databases can be stored on a single device.

The master system device contains four databases:

  • The master system database is used to track system-wide information.
  • The tempdb system database is used for temporary storage.
  • The model system database is used as a template for newly created databases.
  • The pubs sample database is used as an example throughout SQL Server documentation.

A single database can span multiple devices.

The msdb system database is stored on two devices:

  • The msdbdata system device contains only data.
  • The msdblog system device contains only the transaction log.

These system devices and databases are shown as they are created by SQL Server Setup.

A typical database, like mydb, is also stored on two devices:

  • The database data device contains only data.
  • The database log device contains only the transaction log.

A typical database can be expanded in one of two ways:

  • An existing device can be expanded, and then the database can be expanded onto the new space on the existing device.
  • A new device can be created, and then the database can be expanded onto the new device.

The following illustration shows all system- and user-defined database and device structures.


SELECT and UPDATE Processing

The SQL Server database engine processes a client request as outlined in the following steps:

A. The SQL language parser receives a standard SQL statement. It resolves, compiles, and optimizes the query, and stores the final query plan in the procedure cache for use. When the query execution is complete, the query plan is immediately freed from the procedure cache.

B. The stored procedure handler receives a request to run a stored procedure. It checks to see if a compiled version of the stored procedure is in the procedure cache and available for use. If so, it uses the compiled version already in the procedure cache. If the stored procedure is not in the procedure cache, the stored procedure is in the procedure cache but is currently being used by another connection, or the stored procedure must be recompiled for some reason (for example, if the stored procedure is created with or executed with the WITH RECOMPILE option), then the resolved version of the stored procedure is loaded from the sysprocedures table, compiled, and stored in the procedure cache for use. The page cache is used for reading from sysprocedures, like all table reads.

C. The sysprocedures table contains a resolved version of a stored procedure called a query tree. This intermediate form has already been parsed, but it has not been compiled or optimized. Views and other database objects are also stored in sysprocedures.

D. The procedure cache contains a compiled version of a query or stored procedure called a query plan. This final form has been optimized and contains complete details for executing the query, including join plans and index usage.

E. To process a SELECT query plan, data and index pages must be read from the database. SQL Server checks to see if the necessary pages are in the page cache. Any pages already in the page cache are used. Any pages not in the page cache are read from the appropriate database device(s) into the page cache for use.

F. To process an UPDATE, a DELETE, or an INSERT query plan, data, index and log pages must be read from and written to the database. Just as in the SELECT case, SQL Server checks to see if the necessary pages are in the page cache. Any pages already in the page cache are used. Any pages not in the page cache are read from the database device(s) into the page cache for use. Any pages in the page cache that are changed are marked as "dirty." This includes changed log pages used to store transaction log records or data and index pages changed to reflect actual data changes. Any pages that are completely unchanged remain "clean."

G. When a transaction ends (COMMIT TRAN, ROLLBACK TRAN, or transaction abort) all dirty (changed) log pages are immediately written to disk to ensure recoverability. Note that data and index pages are not written to disk by this process.

H. Data, index, or log pages are written to disk at various times. In all cases, the appropriate log pages are always written to disk before the corresponding data or index pages. This ensures recoverability. For this reason, the transaction log is known as a "write-ahead" log. Data and index pages can be written to disk before a commit if necessary because the transaction log contains all the information necessary to roll the changes back if the transaction does not commit. Also, if a power failure (or similar circumstance) causes a shutdown with dirty pages in the page cache, the appropriate changes can be rolled forward using the transaction log.

I. Data and index pages are written to disk at various times. When the lazy writer determines that the number of "free" or unused pages in the page cache is below a certain value (the free buffers server-configuration value), it begins to "flush" or write blocks of pages to disk until enough free pages are available in the page cache. It does this to avoid checkpoints and single-page writes, both of which are relatively expensive. When a checkpoint occurs, all dirty pages (log, data, and index) are written to disk. When a page is needed because a new page must be read from disk but no free pages are available in the page cache, a single page is taken from the least-recently-used (LRU) list, flushed, and made free for use.

The following illustration shows the processing and page flows for SELECT and UPDATE.


Network Architecture

SQL Server communicates with clients by using a network interface layer called the Net-Library. This interface layer and the Open Data Services layer account for the bulk of the SQL Server network architecture.


Net-Library

A Net-Library is a network interface that is specific to a particular network interprocess communication (IPC) mechanism. SQL Server uses a common internal interface between Open Data Services, which manages its use of the network, and each Net-Library. By doing this, all network-specific considerations and calls are isolated to just that Net-Library. There may be multiple Net-Libraries loaded, one for each network IPC mechanism in use—for example, one for named pipes, another for TCP/IP sockets, another for SPX, and yet another for Banyan VINES SPP. Microsoft SQL Server uses this Net-Library abstraction layer at the server as well as the client, making it possible to simultaneously support clients on different networks. Windows NT allows multiple protocol stacks to be in use simultaneously on one system.

It is important to distinguish between the IPC mechanism and the underlying network protocol. IPC mechanisms used by SQL Server include named pipes, SPX, and Windows Sockets. Network protocols include NetBEUI, NWLink (SPX/IPX), TCP/IP, and VINES IP. Named pipes, a common IPC used in SQL Server environments, can be used over multiple network protocols (named pipes can be used efficiently over NetBEUI, NWLink SPX/IPX, and TCP/IP, all simultaneously).

Note SQL Server in other environments has traditionally supported only a single IPC mechanism, usually TCP/IP sockets, that was hard-coded directly into the network handler. All clients needed to communicate with that IPC mechanism, and nothing else, and usually only with a single network protocol.

SQL Server uses a multiprotocol networking library that will listen for incoming network connections on named pipes, a TCP/IP port, and an SPX socket. The named pipe name, TCP/IP port, and SPX socket number are usually chosen dynamically.

If you want users on the Internet to connect to your SQL Server using TCP/IP and your organization is using a firewall system to isolate the network containing the SQL Server from the rest of the Internet, ensure that SQL Server uses a particular port number for its incoming connections. By doing this, the firewall system will forward connections to that particular port number on your SQL Server.

For instructions about configuring SQL Server to listen for incoming connections, see What's New in SQL Server 6.5, available in the documentation set shipped with Microsoft SQL Server.


Open Data Services

Open Data Services functions as the network connection handler for SQL Server. In the past, Open Data Services and the SYBASE Open Server were often referred to "conceptually" as the front end of SQL Server. However, they were different implementations that attempted to perform the same function. But it is literally true that SQL Server is an Open Data Services application. SQL Server uses the same Open Data Services library (Opends*.dll) as any other Open Data Services application. Open Data Services manages the network, listening for new connections, cleaning up failed connections, acknowledging "attentions" (cancellations of commands), and returning result sets, messages, and status back to the client. SQL Server clients and the server speak a private protocol known as tabular data stream (TDS). TDS is a self-describing data stream. In other words, TDS contains "tokens" that describe column names, data types, events (such as cancellation), and return status in the client/server "conversation." On the server side, SQL Server writes directly to TDS, passing through Open Data Services. On the client side, open interfaces of DB-Library and Open Database Connectivity (ODBC) package the SQL statements in TDS format. Both DB-Library and ODBC use a client implementation of the Net-Library.

For more information, see these titles in Microsoft SQL Server Books Online:

  • Programming ODBC for Microsoft SQL Server
  • Microsoft SQL Server Programming DB-Library for C
  • Microsoft SQL Server Programming DB-Library for Visual Basic


SQL Distributed Management Framework

As applications become less centralized and more distributed, managing multiple, distributed databases becomes more difficult. Graphical tools, like the Microsoft SQL Server user interface, SQL Enterprise Manager, are one part of the solution because they allow you to administer multiple distributed servers from a central console. Another critical part of the solution is a robust scripting language for automating repetitive administrative tasks.

SQL Distributed Management Objects (SQL-DMO) defines all aspects of the Microsoft SQL Server database engine and services. SQL-DMO is part of a comprehensive framework called SQL Distributed Management Framework (SQL-DMF), which is an integrated framework of objects, services, and components used to manage Microsoft SQL Server. SQL-DMF provides a flexible and scalable management framework that is adaptable to your specific needs. SQL-DMF reduces the need for user-attended maintenance tasks, such as database backup and alert notification, by providing services that interact directly with SQL Server.

All the key components of SQL-DMF are core elements of SQL Server. SQL-DMF enables you to manage the SQL Servers in your enterprise by allowing you to define scenarios and corrective actions and to trigger either alerts to notify someone of the problem or tasks to correct the problem.

The following illustration shows the relationship among the SQL-DMF components.

At the lowest level of this framework, SQL-DMF provides direct access to the SQL Server engine and to services executed from the command prompt using Transact-SQL. The second level of the framework is a set of distributed management objects that provides an object interface to the SQL Server engine and services. The top level of the framework is a graphical administration tool, SQL Enterprise Manager, that provides an interface for managing a multiple-server environment. The framework also provides services for replication, scheduling, and creating alerts.


The SQL-DMO Model

SQL Server and its components are completely represented by the SQL-DMO model. The main object, SQLServer, is used with other objects that describe the server's elements such as Login, Database, and Table.

For anyone familiar with Visual Basic, the concept of objects is not new. SQL-DMO, like Visual Basic controls, has properties and methods. Properties represent the object's attributes; methods represent the object's functions. SQL-DMO provides over 40 objects and over 1,000 properties and methods. Some example objects include databases, rules, triggers, tables, columns, views, users, groups, publications, and indexes. The object-oriented model is so complete and flexible that the Microsoft SQL Server management tool, SQL Enterprise Manager, is written using SQL-DMO.

Unlike Visual Basic controls, SQL-DMO does not have a visual component nor events that are triggered by the mouse or keyboard. SQL-DMO provides objects used for controlling the SQL Server engine and its components. These objects expose appropriate properties and methods for all administration and database definition options.

The following illustration shows the complete set of objects in the SQL-DMO model and how the objects relate to one another in scope and hierarchy. The Application objects and the SQLServer object treat the application as their parent. Other objects depend on the availability of their parent object. These dependencies are represented in the diagram by indented sublevels. After the application has declared an object, the application can modify the object's properties and call its methods.

Each object represents a physical element of a SQL Server system. The SQLServer object is the base object from which all other SQLServer objects branch in an object hierarchy. The scope of an object is determined by its parent because an object can be instantiated (connected, added, or made to represent a SQL Server element) only after its parent has been instantiated. For example, the SQLServer object is the Database object's parent, which means that a Database object can be instantiated only after the SQLServer object has been instantiated.

The model also shows two more important aspects of SQL-DMO: Collections and Application objects.

Collections are a group of objects of the same type that have the same parent. For example, all the Table objects that belong to the pubs database, the sample database installed with SQL Server, are members of the pubs Tables collection.

The collection is a powerful programming concept. Using a collection, you can refer to a specific object down the object hierarchy without declaring it explicitly. You can iterate through each member of a collection without specifying the name of each object. You can also add or remove objects collectively. Collections make it easy to write an application that iterates through all objects of the same type.

A collection's name is the plural of the type of object it contains. For example, a Tables collection contains Table objects.

Application objects are a group of objects primarily used to hold information, such as query results, permission information, or backup information, in a particular form. For example, the Backup object is used to store information about a backup and is passed as a parameter when the Database object's Backup method is called. Application objects can exist in the application prior to the creation of a SQLServer object.


Database Internals

Microsoft SQL Server internal structure provides a superior platform for delivering cost-effective information solutions.

A SQL Server database is essentially a storage area for database objects. These objects, such as tables, indexes, views, data types, and stored procedures, are used to represent entities of interest to the database users. These objects represent entities that are externally visible to users of the database; they are not the elements that SQL Server uses internally to build the database.

The following sections describe:

  • The internal structure of SQL Server databases.
  • The physical files used to store the databases.
  • How the system tables, sysdevices, sysdatabases, sysusages, and syssegments, catalog and manage these structures.
  • The basic layout of SQL Server tables and indexes.


Databases

All SQL Server systems have four system databases (master, tempdb, model, and msdb), plus one or more user databases. All of these databases are built from the following internal components.


Pages

All SQL Server physical structure is based on 2K blocks called pages. The page is the fundamental building block for SQL Server objects, such as tables and indexes. It is also the fundamental unit for most SQL Server actions, such as reading, writing, caching, and locking.

There are six types of pages in a SQL Server database, as shown in the following table.

Page type | Contains
Data | Data rows
Index | Index rows
Log | Log rows recording data changes for use in recovery
Text/Image | Text and image data
Distribution | Distribution statistics on indexes for the purpose of optimizing queries
Allocation | Data allocation information used by SQL Server to manage space in a database

Pages for many objects, such as data pages, log pages, and text/image pages, are chained together in linked lists. These are called page chains, such as the data-page chain for a table, or a chain of text pages for a row.

Every page has a header containing standard information such as the object ID of the object the page is allocated to and the next/previous pointers that link page chains.

Logical Page Numbers

Every page in a database is assigned a page number, called a logical page number. The first page in a database is logical page 0, and the page numbers increment by 1 to the last page in the database. Since the logical page numbers in each database start at 0, logical page numbers are duplicated among databases. It also means a logical page number is relevant only if there is also an indication of which database the page is in. The page pointers that link together page chains are simply the logical page number of the page that the pointer references.


Extents

SQL Server always allocates space for objects in units of eight contiguous pages called extents. All pages in the extent are owned by the same object. When SQL Server needs to give more pages to an object, the server designates a new extent for that object. If all the rows in an extent are deleted, SQL Server frees the extent for use by any other object needing space. All of the extents for an object are chained together in a doubly linked list called an extent chain. An extent chain can span multiple allocation units.


Allocation Units

SQL Server allocates space to databases in units of 256 continuous pages called allocation units. Each allocation unit is 512K, or 0.5 MB in size. Each allocation unit holds 32 (256/8) extents.

The first page in each allocation unit is an allocation page. The allocation page does not contain any user data; it contains system data (header information) and 32 extent data structures. Each extent data structure:

  • Indicates which object owns the extent.
  • Indicates which pages in the extent are in use and which are not in use.
  • Contains pointers to other extents in the extent chain that are owned by that object.

The following illustration shows the structure of an allocation page.


Devices

The SQL Server term for a physical file used by the server is device. There are three types of devices:

  • Disk dump devices—define SQL Server dump files that reside on disk drives.
  • Tape dump devices—define SQL Server dump files that reside on tape drives.
  • Database devices—The physical disk files that hold databases, or portions of databases.

Devices are built of 2K pages, just like databases are.


DISK INIT

Devices can be created in SQL Enterprise Manager or by using the Transact-SQL DISK INIT statement. For information about the DISK INIT statement, see the Microsoft SQL Server Transact-SQL Reference.


Virtual Page Numbers

The pages in SQL Server devices are identified by virtual page numbers, just as the pages in databases are identified by logical page numbers. While logical page numbers start at 0 for each database and can be duplicated, virtual page numbers do not start over with each device. Each virtual page number is unique within SQL Server.

Virtual page 0 in SQL Server is always the first page in the master device, which is created as part of the installation process. The virtual page numbers for the master device start at 0 and increment by 1 to the end of the device. If the system was installed with the default 25 MB master device, the starting virtual page number is 0, and the ending page number is 12799 ((25*512)-1) as shown in the following illustration.

The starting virtual page number for all other devices is calculated by multiplying the VDEVNO specified in the previous DISK INIT statement by the number 16777216. This ensures there is no duplication in virtual page numbers between devices. The virtual page numbers for each device start at the number calculated from the VDEVNO and increment by 1 until they meet the limit defined by the DISK INIT SIZE parameter. For example, if the DISK INIT statement specified a VDEVNO of 8 and a SIZE of 2048, the starting virtual page number for that device would be 134217728 (16777216 * 8), and its virtual page numbers would increment by 1 to 134219775 (134217728 + SIZE – 1).


sysdevices

The information about devices is stored in the system table master.dbo.sysdevices. If a user selected the name, phyname, low, and high columns for a default master device, the output would be:

NAME
PHYNAME
LOW
HIGH

master
c:\mssql\data\master.dat
0
12799

Low is the starting virtual page number for the master device (0), and high is the ending virtual page number (12799). If you then execute the following DISK INIT statement, another row would be added to the sysdevices table with the following information (see the result set), where LOW = VDEVNO*16777216, and HIGH = LOW + SIZE – 1.

DISK INIT NAME = 'sample', PHYSNAME='d:\sqldata\sample.dat', VDEVNO=1, SIZE=20480

NAME

PHYNAME

LOW

HIGH

sample

d:\sqldata\sample.dat

16777216

167797695


Mapping Databases to Devices

When databases are created (using either SQL Enterprise Manager or the Transact-SQL CREATE DATABASE statement), they are mapped across one or more devices. This mapping can be changed using either SQL Enterprise Manager or the ALTER DATABASE statement. This section discusses how databases are mapped onto devices, and how this is represented in the system tables in the master database.


Logical and Virtual Page Numbers

Each logical page number in a database relates to an underlying virtual page number in a device. For example, if you execute the following statements:

DISK INIT
NAME = 'sample',
PHYSNAME = 'c:\mssql\data\sample.dat',
VDEVNO = 8,
SIZE = 2048
GO
CREATE DATABASE sampledb ON sample = 4
GO

You create the sample device, then map the sampledb database to that device. Both the device and the database are the same size. The sample device has virtual page numbers from 134217728 to 134219775, and the sampledb database has logical page numbers from 0 to 2047. The logical page numbers map to the virtual page numbers as shown in the following illustration.


Fragments

Fragments are the fundamental unit in which databases are allocated. Each database can have a maximum of 32 fragments. The CREATE DATABASE statement will generate 1 or 2 fragments (depending on the syntax used), and each use of the ALTER DATABASE statement after that will generate an additional fragment. Each fragment is contained in only one device; fragments do not span devices. Each database can have multiple fragments on one device and can have fragments on multiple devices.

For example, assume that a system has two user devices, dev1 with 20 MB and dev2 with 10 MB. The following statement creates a sample database with 2 fragments, one of 10 MB on dev1 holding data and one of 10 MB on dev2 holding the log. There is still 10 MB free on dev1.

CREATE DATABASE sample ON dev1 = 10 LOG ON dev2 = 10

If the sample database then starts running out of data space, use ALTER DATABASE to generate an additional fragment:

ALTER DATABASE sample ON dev1 = 10

After ALTER DATABASE has completed, sample has 3 fragments; dev1 contains the original data fragment of 10 MB plus the last data fragment of 10 MB and dev2 contains the log fragment generated by CREATE DATABASE. Each database fragment has a line in the master.dbo.sysusages table.

When you create a database fragment on a device that does not have enough space to hold the entire fragment, SQL Server maps as many allocation units onto the device as will fit in the space available. For example, to allocate a device dev1 with 4 MB, you specify SIZE = 2148 in the DISK INIT statement. If the DISK INIT statement is specified as SIZE = 2140, then there are only 3.98 MB on dev1.

When you execute the following statement, SQL Server allocates as many allocation units to the device as it can, so the short database ends up with only 3.5 MB:

CREATE DATABASE short ON dev1 = 4


Segments

Segments are named collections of fragments within a database used to control the allocation of pages in a database. Before the widespread availability of RAID systems, segments offered a mechanism to allocate specific database objects to different disk drives to spread physical I/O across the drives.

When using segments, users creating objects can specify the segment in which they want SQL Server to allocate their objects. This allows I/O to be split between drives, rather than being concentrated on a single device.

The statements that create and extend segments work at the device level. When a segment name is applied to a device, it is applied to all fragments of the affected database on that device.

With the advent of inexpensive RAID arrays and the RAID capabilities of Windows NT, user-defined segments are no longer recommended. Setting up a RAID stripe set to spread I/O across an array of drives yields similar performance gains to setting up database segments, and RAID is easier to administer.

SQL Server continues to use its system segments to control the allocation of space in databases, so an understanding of how these system segments work within databases is still important. SQL Server always uses three system segments:

  • The system segment contains all pages allocated for SQL Server system tables.
  • The logsegment segment contains all pages allocated to the log, which is contained in the syslogs table.
  • The default segment contains all pages allocated to user-defined objects that did not have a user-defined segment specified when they were created.

When you create a database with separate data and log portions, what actually happens is that the system and default segments are mapped to the database fragment on dev1, and the logsegment segment is mapped to the database fragment on dev2.

CREATE DATABASE sample ON dev1 = 10 LOG ON dev2 = 5

This means that all pages allocated to system tables (except syslogs) and user tables or indexes are allocated from the system and default segments on dev1, while all pages for syslogs are allocated from the logsegment segment mapped on dev2.

You then use ALTER DATABASE to generate an additional fragment:

ALTER DATABASE sample ON dev3 = 10

SQL Server allocates 10 MB for the sample database on dev3 and then maps the system and default segments to the fragment to make it a data device.

If you really want this new allocation to be used for the log, then following the preceding ALTER DATABASE statement, you must execute the following stored procedure:

sp_logdevice sample, dev3

sp_logdevice removes the mapping of the system and default segments on dev2, and maps the logsegment segment to dev3.


System Table Mappings

This section tells how the preceding components are represented in the system tables. This section assumes that SQL Server is setup with all default settings and that the following statements have been executed:

DISK INIT NAME = 'SampleData', PHYSNAME='c:\mssql\data\smpldata.dat', VDEVNO=1, SIZE = 20480
GO
DISK INIT NAME = 'SampleLog', PHYSNAME='c:\mssql\data\smpllog.dat', VDEVNO=2, SIZE = 10240
GO
CREATE DATABASE sample ON SampleData = 10 LOG ON SampleLog = 10
GO
ALTER DATABASE sample on SampleData = 10
GO

Devices

The master.dbo.sysdevices table records the information for each device. The following SELECT statement returns the data that helps to understand how the database devices are structured:

SELECT low, high, vdevno = low / 16777216, name, phyname
FROM sysdevices
WHERE status < 16
ORDER BY low

When this query is executed on the sample system, here is the result set:

LOW
HIGH
VDEVNO
NAME
PHYNAME

0

12799

0

master

c:\mssql\data\master.dat

16777216

167797695

1

SampleData

c:\mssql\data\smpldata.dat

33554432

33564671

2

SampleLog

c:\mssql\data\smpllog.dat

2113929216

2113930239

126

MSDBLog

c:\mssql\data\msdblog.dat

2130706432

2130709503

127

MSDBData

c:\mssql\data\msdb.dat

Interpreting this based on the discussion of sysdevices and fragments above, these results show that SQL Server Setup created three system devices: master, MSDBLog, and MSDBData and that the script shown earlier created two user-defined devices: SampleData and SampleLog. The low and high columns list the range of virtual page numbers for each device, while the vdevno column calculates the vdevno specified for each device DISK INIT.

Databases
The master.dbo.sysdatabases table contains the information for each database. The only information in sysdatabases that is important for mapping databases to devices is the unique database identifier (DBID) assigned to each database as shown by the following query and result set:

SELECT name, dbid
FROM sysdatabases
ORDER BY dbid
NAME    DBID

master    1
tempdb    2
model    3
pubs    4
msdb    5
sample    6

The result set shows that Setup created the four system databases: master, tempdb, model, and msdb, and installed the pubs example database and that the script shown earlier created the sample database.

Fragments
master.dbo.sysusages maps each database to the underlying devices. Each database fragment has one row in sysusages. The following query retrieves information about how the databases map to the devices:

SELECT dbname = sd.name, su.*
FROM sysusages su, sysdatabases sd
WHERE su.dbid = sd.dbid
ORDER BY su.dbid, su.lstart

Here is the result set for the preceding query on the sample system:

DBNAME

DBID

SEGMAP

LSTART

SIZE

VSTART

master

1

7

0

1536

4

master

1

7

1536

7168

3588

tempdb

2

7

0

1024

2564

model

3

7

0

512

1540

pubs

4

7

0

512

2052

pubs

4

7

512

1024

10756

msdb

5

3

0

3072

2130706432

msdb

5

4

3072

1024

2113929216

sample

6

3

0

5120

16777216

sample

6

4

5120

5120

33554432

sample

6

3

10240

5120

16782336

The segmap column indicates what segments map to what fragment. All segments are assigned a segment number in the syssegments table in each database. The system segment is always segment 0, the default segment is always segment 1, and the logsegment segment is always segment 2. The system maps these into segmap by turning on a bit. If segment 0 (system) maps to the fragment, the system turns on the low order (or 1 bit) in the segmap column. If segment 1 (default) maps to the fragment, the second lowest order bit (the 2 bit) is turned on. If segment 3 (logsegment) maps to the fragment, the third lowest order bit (the 4 bit) is turned on.

Segmap value | Bits turned on | Segments applied
7 | 1 + 2 + 4 | System + default + logsegment (data + log)
4 | 4 | Logsegment (log only)
3 | 1 + 2 | System + default (data only)

In most current systems and where all fragments are in one of these three states (data only, log only, or data log), all the segmap values in sysusages will be either 3, 4, or 7. In systems containing user-defined segments, or where you may have been working with the segments, there may be other segmap values present. For information about how to map the segmap values back to the user-defined segments, see Knowledge Base Article Q101241.

The sysusages.lstart column indicates the logical page number within the database at which the fragment starts. The size column indicates how many pages are in that fragment. From the combination of the segmap, lstart, and size columns, you can tell that the sample database has three fragments. Each fragment is 10 MB in size (size/512). The first fragment starts at logical page 0 and is a data-only segment (segmap equals 3), the second fragment starts at logical page 5120 and is a log-only statement (segmap equals 4), while the last segment starts at logical page 10240 and is another data-only segment. This information relates to the logical ordering of the database fragments within the database but indicates nothing about their physical location in the devices.

The vstart column indicates the physical location of each fragment. vstart is the virtual page number within a device of the first page in each fragment. The location of the fragment can be found by mapping the vstart value back to the low and high columns in sysdevices. For example, the vstart of the first fragment in the sample database is 16777216. When that is matched against sysdevices.low, it is the same as the low value for the SampleData device. This indicates that this fragment starts on the first page in the SampleData device. The vstart of the second fragment in the sample database is 33554432, which maps to the first page of the SampleLog device. The vstart of the third fragment in the sample database is 16782336. Looking at sysdevices, we find that this value is larger than the low value for the SampleData device but smaller than the high value for SampleData, so the fragment is contained in the SampleData device.

One thing to note is that the lowest vstart, for the master database, is 4. This is because the first three pages of the master device are used internally by the system and are never allocated to a database.


Tables and Indexes

Objects in a SQL Server database are stored as a collection of 2K pages. This section describes how the pages for tables and indexes are organized.

The data for each table is stored in a doubly linked list of 2K data pages. Each data page has a 32-byte header containing the table object identifier, a pointer to the previous page in the data chain, a pointer to the next page in the chain, and other internal data. Data rows make up the rest of the data page after the header.

All of the page chains for tables and indexes are anchored by page pointers in the sysindexes table. Every table will have one chain of data pages, plus additional structures to implement any indexes defined for the table.

Each table and index has a row in the sysusages table uniquely identified by the combination of the object identifier (id) column and the index identifier (indid) column.

  • A table with no clustered index has a row in sysindexes with indid = 0. This row has page pointers to the start and end of the data page chain for that table.
  • If a clustered index is defined for the table, the row with indid = 0 is replaced by a row with indid = 1. The row with indid = 1 points to both the start of the data page chain for the table and the top of the clustered index.
  • Each nonclustered index created for the table has a row in sysindexes with an indid from 2 through 254. Each row has one pointer to the top of the index and another pointer to the start of the lowest level of the index.
  • Each table that has one or more text or image columns also has a row in sysindexes with indid = 255.

Table Without Indexes

The simplest table structure is a table without indexes. This type of table has one row in sysindexes with indid = 0. The column sysindexes.first points to the first page in the data chain for the table. sysindexes.root points to the page at the end of the data chain for the table. The data chain is a doubly linked list of data pages holding the data rows for the table. The data pages and the rows within them are not stored in any specific order. All inserts simply go to the end of the data page chain.

Clustered Index

The next step in complexity is a table with a single clustered index. This table has only one row in sysindexes, which will have indid = 1. sysindexes.first points to the first page in the data chain. The pages in the data chain and the rows within them are ordered on the value of the clustered index key. All inserts are made at the point the key value in the inserted row fits in the ordering sequence. sysindexes.root points to the top of the clustered index.

SQL Server indexes are organized as binary trees. Each page in an index holds a page header followed by index rows. Each index row contains a key value and a pointer to either a page or a data row. Each page in an index is called an index node. The top node of the binary tree is called the root node. The bottom layer of nodes in the index are called the leaf nodes. In a clustered index, the data page chain makes up the leaf nodes. Any index levels between the root and the leaves are collectively known as intermediate levels.

The following illustration shows the structure of a table with a clustered index.

Note that the data rows are stored in sequence on their key value. sysindexes.first points to the start of the data chain; the data chain is also the leaf level of the index. The data rows in the data chain are all ordered on the indexes key. There is one intermediate level in the index. Sysindexes.root points to the root of the binary tree, and from the root node the system can navigate to any node in the structure. Each index node contains index rows that indicate the starting key value and page number of each page in the next lower level.

Nonclustered Index

Nonclustered indexes have the same binary tree structure, but have one significant difference from clustered indexes. This is that the data rows are not stored in order on the keys of the nonclustered index. From the point of view of the nonclustered index, the data rows appear to be randomly distributed through the data pages. Because of this, the leaf layer of a nonclustered index does not consist of the data page chain. The leaf nodes instead contain index rows consisting of key values and pointers to the row (or rows if the index is also nonunique) that have that key value. Also, sysindexes.first points to the first page of the leaf layer of the index, not to the start of the data pages as in the case of a clustered index.

Distribution Pages

All indexes have a distribution page that contains distribution statistics about the current key values for that index. These statistics are used by the SQL Server optimizer to determine how effectively that index would support the query being optimized. sysindexes.distribution points to the distribution page for the associated index.

Text and Image Pages

Text and image values are not stored as part of the data row but are instead stored in separate page chains of their own. For each text or image value, all that is actually stored in the data row itself is a 16-byte page pointer. For each row, this pointer points to the start of a page chain holding the text or image pages. A row containing multiple text or image columns will have one pointer and chain combination for each text or image column in the row.

The space allocations for all the text and image columns of each table are managed from one row in sysindexes, which has an indid of 255. If a table has multiple text or image columns, it will still only have one row in sysindexes with an indid of 255.

If a row containing a text or image column is inserted with a text or image value set to NULL, then no pages are allocated for that text or image chain. As soon as the row has its text or image value updated, at least one page is allocated to hold the new data value.

In the following query, even though the user specified NULL as a data value, it will still cause the allocation of a 2K text page.

UPDATE mytable SET textcol = NULL
WHERE keycol = 'somevalue'

Text and image pages can each hold 1,800 bytes of data.

Log Pages

The log in a SQL Server database is stored as the syslogs system table. syslogs can be thought of as simply a table with no indexes. The log pages are the data page chain of the syslogs table.


Microsoft Distributed Transaction Coordinator

Microsoft Distributed Transaction Coordinator makes distributed applications easy to create.

Microsoft Distributed Transaction Coordinator (MS DTC) manages transactions on one or more SQL Server systems, guaranteeing transaction integrity and recoverability. Its transparent two-phase commit supports server-to-server procedures and simplifies application development.

MS DTC coordinates transactions across a network of Microsoft Windows NT–and Microsoft Windows 95–based systems. Modularity, or structuring an application as independent modules, allows you to build complex systems from simpler parts and to reuse software. Object-oriented concepts and the Microsoft Component Object Model (COM) provide a technique that allows you to write modular applications.

When an application is structured as a group of components, the individual parts can reside together in a single computer, or they can interact by using remote-procedure calls across a network. So, components offer both modularity and natural distribution.

Structuring an application into independent components can create a component management problem. Monolithic programs fail and are restarted as a unit. However, with a modular system, the failure of one component must not corrupt the others. There must be a way to isolate faults and limit fault propagation. Transactions provide modular execution and simplify and automate fault handling. They provide a simple conceptual execution framework for both implementers and users.

The user thinks of a transaction as a single change event that either happens or doesn't happen. Implementers think of a transaction as a programming style that allows them to write modules that can participate in distributed computations. Suppose you want to transfer money from one bank account to another. The implementers and the users want to make sure that either both accounts change or neither changes. It is hard to make this work in a distributed system—computers can fail and messages can be lost. Transactions provide a way to bundle a set of operations into an atomic execution unit.

The atomic all-or-nothing property appears throughout life. For example, if you enter a contract, an escrow officer coordinates the transaction by collecting the signatures of each party to the contract. The contract is final when the escrow officer announces that everyone has signed. A minister conducting a marriage ceremony first asks the bride and groom, "Do you take this person to be your spouse?" If they both respond "I do," the minister pronounces them married. A director on a movie set first asks, "Ready on the set?" If all respond "Yes," the director then calls, "Action!"

These scenarios illustrate the basic principle of a transaction: several independent entities must agree. If any party disagrees, the deal is off. If they agree, the transaction can occur. MS DTC performs this transaction coordination role for the other components of the COM architecture.

In MS DTC terminology, the director is called the transaction manager. The participants in the transaction that implement transaction-protected resources, such as relational databases, are called resource managers.

An application begins a transaction by calling the transaction manager's BeginTransaction method. This creates a transaction object that represents the transaction. The application then calls the resource managers to do the work of the transaction.

The application's first call to each resource manager identifies the application's current transaction. For example, if the application is using a relational database, it calls the ODBC interface, which associates the transaction object with the ODBC connection. Thereafter, all database calls made over that connection are performed on behalf of the transaction until the transaction is ended.

When a resource manager first does work on behalf of a transaction, it enlists in the transaction by calling the transaction manager. As the transaction progresses, the transaction manager keeps track of each of the resource managers enlisted in the transaction.

Typically, the application completes the transaction with a call to the Commit transaction method. If the application is unable to complete, the application calls the Abort transaction method, which undoes the transaction's actions. If the application fails, MS DTC aborts the transaction.

When the application successfully completes the transaction's work, it calls the MS DTC to commit the transaction. MS DTC then goes through a two-phase commit protocol to get all of the enlisted resource managers to commit. The two-phase commit protocol ensures that all the resource managers commit the transaction or all abort it.

In the first phase, the MS DTC asks each resource manager if it is prepared to commit. If all participants say yes, then in the second phase MS DTC broadcasts the commit message to all of them. If any part of the transaction fails, if a resource manager fails to respond to the prepare request, or if a resource manager responds no, then MS DTC notifies all of the resource managers that the transaction aborted.

Transaction managers are a key part of most database systems. Transaction managers are also an optional part of some operating systems. It is thought that transactions are essential for distributed applications—transactions provide modular execution, which complements COM modular programming. Therefore, Microsoft implemented transaction management software for both Microsoft Windows 95 and Microsoft Windows NT operating systems.

In its first release, MS DTC works with one resource manager: Microsoft SQL Server. It also operates with several transaction processing monitors, including Encina, Top End, and Tuxedo. MS DTC implements the OLE transaction interfaces. All OLE transaction interfaces are public so that any resource manager can become an OLE transaction resource manager. In the future, Microsoft and other software companies will add other transactional resource managers, such as distributed object systems, transactional file systems, transaction queuing systems, and workflow management systems.


The ACID Properties

The ACID properties are four characteristics of transactions: atomicity, consistency, isolation, and durability. Transactions provide the ACID properties.

Atomicity

A transaction either commits or aborts. If a transaction commits, all of its effects remain. If it aborts, all of its effects are undone. For example, in renaming an object, the new name is created and the old name is deleted (commit), or nothing changes (abort).

Consistency

A transaction is a correct transformation of the system state. It preserves the state invariants. For example, by adding an element to a doubly linked list, all four forward and backward pointers are updated.

Isolation

Concurrent transactions are isolated from the updates of other incomplete transactions. These updates do not constitute a consistent state. This property is often called serializability. For example, a second transaction traversing the doubly linked list mentioned in the consistency example will see the list before or after the insert, but it will see only complete changes.

Durability

After a transaction commits, its effects persist even if there are system failures. For example, after the rename in the atomicity example, the object will have the new name even if the system fails and reboots right after the commit completes.

It is up to the application to decide what consistency is and to bracket its computation with BeginTransaction and Commit transaction methods to delimit these consistent transformations. Transactional resource managers provide consistent, isolated, and durable transformations of the objects they manage. MS DTC manages transactions that involve multiple resource managers, perhaps distributed among multiple computers. MS DTC creates transaction objects, tracks migration of transactions among resource managers, and implements the two-phase commit protocol to make these transactions atomic and durable.


Execution Scenarios

Transactions are execution units that either commit or abort. If a transaction commits, its effects are durable. If a transaction aborts, its effects are undone. Application programmers, resource managers, and transaction managers cooperate to implement the ACID properties. The following sections describe the role of each of these participants.


Application Programmer

The application begins a transaction by getting a transaction object. All subsequent work is associated with that transaction object. When the program reaches a consistent state, it calls the Commit transaction method. If the commit succeeds, the transaction is durably committed. If the commit fails, the transaction is aborted. If the program finds that it cannot complete the transaction, it may call the Abort transaction method to undo the transaction's effects. This is a simple way to clean up complex failure cases.

If the application fails before it commits the transaction, the transaction manager will abort the transaction and tell each enlisted resource manager to undo the transaction's effects. If a resource manager fails, the transaction will also be aborted. Once the transaction has successfully committed, the resource managers and the transaction manager will ensure that the transaction's effects are durable, even if there are subsequent failures.


Resource Manager

A resource manager first contacts its local transaction manager to declare its presence. Then the resource manager waits for execution requests from applications. When a request arrives tagged with a new transaction object, the resource manager enlists in the transaction. By enlisting, the resource manager ensures that it will get callbacks from the transaction manager when the transaction commits or aborts. The resource manager then performs the transaction's requests. For example, the transaction might insert, delete, or update records in a relational database. The resource manager keeps enough information to allow it to either undo or redo the transaction's work on those resources. There are many ways to do this; keeping versions of data or keeping a log (journal) of the changes are two common techniques.

When the application commits the transaction, the transaction manager initiates the two-phase commit protocol. The transaction manager first asks each enlisted resource manager if it is prepared to commit the transaction. The resource manager must prepare to commit—it readies itself to either commit or abort the transaction.

Typically, the resource manager records the old and new data in stable storage so that the resource manager can recover even if the system fails. If the resource manager cannot prepare successfully, it informs the transaction manager that it cannot prepare and the transaction manager aborts the transaction. If the resource manager can prepare, it tells the transaction manager and waits for the transaction manager's decision whether to commit or abort the transaction.

Once prepared, a resource manager must wait until it gets a commit or abort callback from the transaction manager. Most transactions commit, although a few transactions abort. Typically, the entire prepare and commit protocol completes in a fraction of a second. If there are system or communication failures, the commit or abort notification may not arrive for minutes or hours. During this period, the resource manager is in doubt about the outcome of the transaction. It does not know whether the transaction committed or aborted. While the resource manager is in doubt about the transaction, it keeps the data modified by keeping the transaction locked, thereby isolating these changes from any other transactions.

The discussion so far shows how distributed transactions are made atomic in a fault-free environment. Now we consider how MS DTC helps resource managers make transactions atomic and durable when a resource manager fails. If a resource manager fails and then restarts, the resource manager must reconstruct the committed state of the resources it manages. The reconstructed state must reflect all of the effects of committed transactions and none of the effects of aborted transactions. When a resource manager fails, all of its enlisted transactions are aborted except for those that prepared or committed prior to the failure. When the resource manager restarts, it asks the transaction manager about the outcome of the in-doubt transactions in which it enlisted. The transaction manager tells the resource manager the outcome of each in-doubt transaction and the resource manager commits or aborts these transactions accordingly.

In summary, the two-phase commit protocol and the resource managers combine to make transactions atomic and durable.


Transaction Manager

The transaction manager is the manager of transaction objects. It creates transaction objects and manages their atomicity and durability. Applications ask the transaction manager to create a transaction object by calling the transaction manager's BeginTransaction method.

When a resource manager first participates in a transaction, it calls the transaction manager to enlist in the transaction. The transaction manager tracks the resource managers who enlist in the transaction. Later the application commits or aborts the transaction, or the transaction is aborted by a resource manager or a failure.

Commit and Abort are additional transaction methods on transactional objects. When asked to commit a transaction, the transaction manager initiates a two-phase commit protocol. During phase one, it asks all enlisted resource managers to prepare. During phase two, the transaction manager tells the resource managers whether the transaction committed or aborted. The two-phase commit protocol has many optimizations, including the read-only optimization and the transfer-of-commit optimization. MS DTC implements some of these optimizations, but the functionality remains the same: atomicity and durability.

The transaction manager keeps a log in safe storage on disk. The log is a sequential file that records transaction events. The transaction manager records transaction starts, enlistments, and commit decisions in the log. During normal processing, the transaction manager only writes the log. If the transaction manager fails, it reconstructs the transaction's most recent state by reading the log. So, the transaction manager uses the log to make its state durable.

The transaction manager also provides an operations interface to manage transactions. It maintains performance counters that can be displayed by using the system performance monitor. It records important operational events in the system log. These events can be displayed by using the system event viewer. It has a graphical management interface that is integrated with SQL Enterprise Manager. The graphical management interface lets the operator configure the system, view transactions, and abort or commit in-doubt transactions.


Distributed Transactions

The discussion so far has assumed that all the applications and resource managers were on a single computer. MS DTC also supports transactions distributed across two or more Windows systems. Each system has a local transaction manager. All applications and resource managers talk to their local transaction managers. The transaction managers cooperate to manage transactions that span systems.

When a transaction first visits a new system (when the first request tagged with the transaction arrives at that system), the two systems involved in the request establish a relationship. The system making the request informs its local transaction manager that the transaction has an outgoing relationship to the transaction manager on the second system. Similarly, the system receiving the request informs its local transaction manager that the transaction has an incoming relationship with the transaction manager on the first system.

These outgoing-incoming relationships form a tree of transaction manager relationships called the transaction's commit tree. The enlisted resource managers are also members of this commit tree; they have an outgoing-incoming relationship to their local transaction manager.

When a distributed transaction commits or aborts, the prepare, commit, and abort messages flow outward on the commit tree. Any node of the tree can unilaterally abort a transaction anytime before it agrees to the prepare request sent at phase one. Once a node has prepared, it remains prepared and in doubt until the commit coordinator tells it to commit or abort the transaction. The root transaction manager of the commit tree is the global commit coordinator. It makes the decision to commit or abort the transaction and is never in doubt.

If a computer fails and then restarts, the transaction manager at that computer will determine the outcome of all in-doubt transactions. The transaction manager reads its log file to determine the outcome of transactions for which it was the commit coordinator. For incoming transactions from other systems, the transaction manager reads the log file to determine if it was previously notified of the transaction's outcome. For incoming transactions that remain in doubt, the transaction manager queries the incoming transaction manager to learn the transaction's outcome. The transaction manager also responds to queries from other transaction managers regarding in-doubt outgoing transactions sent to them.

This is similar to the protocol that transaction managers and resource managers follow at restart. The transaction manager determines the outcome of each in-doubt transaction and, when asked, tells the resource managers the transaction's outcome.

In-doubt transactions are especially troublesome for distributed transactions. System or communication failures can leave transactions in doubt for a long time. While the transaction is in doubt, the resources modified by the transaction remain locked and unavailable to others. MS DTC provides a way for the system operator to resolve transactions that remain in doubt for too long. The operator can use a graphical management interface at the commit coordinator system to determine the transaction's outcome. The operator also can use the graphical management interface at the in-doubt system to force the in-doubt transaction to commit or abort. When the systems reconnect, MS DTC detects these operator actions and it flags inconsistent actions.


MS DTC Summary

Transactions are ACID (atomic, consistent, isolated, durable) modules of execution. They complement the COM structure. Microsoft Distributed Transaction Coordinator (MS DTC) provides a transaction manager for each computer. Applications call the transaction manager to begin a transaction. BeginTransaction returns a transaction object. The application includes the transaction object with requests to resource managers. When a resource manager first begins working on a transaction, it enlists in the transaction. When the application has made a consistent transformation of the state, it asks the transaction manager to commit the transaction with the Commit transaction method. If the application cannot complete the transaction, the application program aborts it by using the Abort transaction method. If the application fails or a participating resource manager fails, then MS DTC aborts the transaction.

MS DTC uses a two-phase commit algorithm in which (1) the transaction manager requests each enlisted resource manager to prepare to commit, and (2) if all successfully prepare, then the transaction manager broadcasts the commit decision. If any resource manager cannot prepare, the transaction manager broadcasts an abort decision to every resource manager and local transaction manager involved in the transaction. While a resource manager is prepared, it is in doubt about whether the transaction committed or aborted. The transaction manager keeps a sequential log so that its commit or abort decisions will be durable. If a resource manager or transaction manager fails, they reconcile in-doubt transactions when they reconnect.

For distributed transactions, each computer has a local transaction manager. When a transaction works at multiple computers, the transaction managers track incoming and outgoing transactions. Each transaction manager performs all the enlistment, prepare, commit, and abort calls for local resource managers (those on that computer). When committing a transaction distributed among several computers, the transaction manager sends prepare, commit, and abort messages to all its outgoing transaction managers. When a transaction manager is in doubt about a distributed transaction, the transaction manager queries the incoming transaction manager. The root transaction manager is never in doubt. If an in-doubt transaction persists for too long, the system operator can force the transaction to commit or abort.


Part 3 - Planning and Implementing Your SQL Server Solution

The articles in Part 3 provide tips to database and system administrators for streamlining database processes and optimizing queries:

  • Backup and Recovery
  • Integrating Database-Web Connectivity
  • Optimizing Queries
  • Hardware Planning
  • Cascading Deletes and Updates of Primary Keys
  • Removing Duplicate Primary Keys from a Table


Backup and Recovery

Microsoft SQL Server provides many fast and reliable ways to back up your data.

This article provides guidelines for proper backup and recovery of SQL Server databases running in production environments. Too often, customers have suffered hardware or other failures, and only then realized that either they did not have backups, or that their backups were done improperly, resulting in unnecessary loss of valuable data. As with any of the information included in this Resource Guide, you should still read and thoroughly understand those chapters pertaining to backup and recovery in the documentation provided with Microsoft SQL Server.


Backup Strategies

The strategy section explains why you should back up your data, how to develop a backup strategy, when and where to back up, and how to test a backup strategy.


Why Back Up?

Today's hardware and software components are many times more reliable than those of the not-so-distant past; however, there is always the threat of some type of failure. It is therefore in your best interest to have a safety net in place at all times to quickly resume production following a failure, with minimal or no loss of data. When people think of situations that could result in the loss of data, they typically think of hard disk crashes. There are, however, other situations that can have the same end result, but are not frequently considered when planning for recovery. These include:

  • Hard disk subsystem failure.
  • Systems software failure.
  • Accidental or malicious use of deletion statements—for example:
    DELETE * FROM prod_table DROP DATABASE customers
    format c:
  • Accidental or malicious use of update statements—for example, expecting to update one row in a table but not qualifying the WHERE clause.
  • Destructive viruses.
  • Natural disasters.
  • Theft.

Microsoft SQL Server provides many fast and reliable ways to back up your data. To ensure that your data is safeguarded, you need to define a reliable backup strategy.


Planning a Backup Strategy

It is always a good idea to include backup strategy planning as a key component of any project. In some cases, the backup strategy may even have a large impact on the design of the application. When planning the backup strategy for a given application, answer the following questions:

  • How often should backups be done?
  • What will be backed up—for example, full database dumps versus transaction log dumps?
  • On what medium will backups be saved: tape, floppy disk, or hard disk?
  • Will backups be performed while users are working or after hours?
  • Will backups be performed manually or automatically?
  • If backups are automated, how will it be verified that they actually occurred without error?
  • If a backup did not occur without error, how will it be redone?
  • How long will backups be saved before reusing the storage medium?
  • Assuming failure, how long will it take to restore to the last backup? Is that an acceptable amount of downtime? If not, what is?
  • Where will backups be stored, and do the appropriate people have access to them?
  • Who is responsible for seeing that backups are performed and performed correctly?
  • Besides the system administrator, does someone else know the proper passwords and procedures to perform backups and, if necessary, restore the backups?

This is by no means a complete list of all the questions you should consider when planning your backup strategy. You will need to answer these questions for every SQL Server environment, and there may be many other questions specific to your particular environment.


Where and When to Back Up

It is best to keep live data and backups on separate computers, or better yet, in different buildings. If databases and/or logs are dumped to disk devices, it is often optimal from a performance standpoint to dump them to local hard drives on the server, as opposed to drives on some other computer on the network. However, from that point they should be copied to tape or to another server so that data and backups are not on the same computer. For convenience, most people choose to have their backups close at hand so that they can get to them quickly if needed. If this is done, keep another copy somewhere offsite, such as a bank safety deposit box, so that in the event of damage to the building, backup of data will remain safe.

The frequency and type of backups you perform will generally depend on two factors: the "acceptable" amount of data that can be lost due to media or other failure, and the volume of transactions that occur on the SQL Server. At many sites, databases are dumped weekly and transaction logs are dumped daily. This can vary widely, however. For systems that have little update activity and that are used primarily for decision-support, only weekly database dumps may be needed. For other high-volume online transaction processing (OLTP) environments, databases might be dumped daily and the transaction logs dumped hourly. The strategy chosen should be one that best fits your environment while providing adequate assurance of recovering needed data.

If backups are performed online, they should be scheduled for times when the server is not being heavily updated because the dumps will slow down SQL Server. In addition, the dumps should be issued on a fixed schedule. By using a fixed schedule, users will always know when the dump is occurring and can expect a slight delay in performance, or they can plan to do other work during that time.


Testing a Backup Strategy

Once a backup strategy has been designed, it should be thoroughly tested. In testing the strategy, as many failures as possible should be simulated so you can be sure there is nothing that could jeopardize the recovery of data. For example, some customers have implemented highly redundant device and disk mirroring with multiple disks in a computer, so that should any one disk drive fail, they can continue operation uninterrupted. This is a good plan, but it does not eliminate the need to do backups. Asking the question, "Will this be sufficient in the event of theft of the computer?" would show that this plan could jeopardize the recovery of data.

Testing a backup strategy will also demonstrate how much time is required to restore databases from backups. If that amount of time is unacceptable, you may want to re-evaluate the frequency with which databases and transaction logs are being dumped, or you may want to look at the feasibility of maintaining a "warm" backup server. Warm backup servers are discussed in the "Managing a Backup Server" section later in this article.


Dumping and Loading Databases

After planning and testing a strategy, it's time to implement it. The next steps are dumping a database, checking the logical and physical consistency of the dumped database, and when the need arises, loading the previously dumped database.


Managing Database Dump Files

SQL Server databases can be dumped to floppy disks, hard disks, or tape. It is a good idea to keep not only the most current dump, but previous dumps or multiple copies of the dump as well—as many as you deem necessary. To illustrate the importance of multiple copies, assume that some failure occurred that resulted in your need to reload the database from a dump. If only one copy of the most current dump were kept, and something destroyed that copy, you would have to reconstruct your data from scratch. To illustrate the importance of previous dumps, imagine that a user accidentally issued a misqualified update or delete statement against one or more tables. This could result in the incorrect modification or loss of large amounts of data, which could go undetected for several days, weeks, or even longer. By keeping a succession of previous dumps and multiple copies of the current dump, you provide yourself with safety nets for recovery.

SQL Server allows you to specify whether the new dump should overwrite or be appended to the existing contents of the tape. The tapes can then be circulated for reuse in least-recently-used order. SQL Server provides a configuration parameter, "media retention," that helps ensure that a new dump does not overwrite an existing dump too soon. The sp_configure system stored procedure can be used to set the "media retention" parameter, which specifies the number of days that must pass before an existing dump can be overwritten by a new one. SQL Server allows you to specify the size of the dump/load buffer in 32-page increments. The sp_configure system procedure can be used to set the backup buffer size parameter. For example, a backup buffer size value of 5 means that a buffer of 160 pages (5*32) will be used.

When a database is dumped, SQL Server dumps not only the data portion but also the transaction log for that database as well. The transaction log must be included in the dump so that when the database is later loaded, transactions that were in progress during the dump can be properly rolled back. Because the transaction log is dumped with the database, the resulting dump file may be larger than the data portion of the database. For example, assume you have a 100 MB database with a 25 MB transaction log. If both the database and the log are nearly full, the dump file would be approximately 125 MB when the database is dumped. Be sure to allow enough room on the media you are dumping to for both the data and log portions of the database being dumped.


Checking Database Consistency

It is recommended that you run DBCC CHECKDB, DBCC NEWALLOC, DBCC TEXTALLOC, and DBCC CHECKCATALOG on a database either just before or just after dumping it to check the logical and physical consistency of the database. Because transactions can occur during or after the database consistency check (DBCC) but before the dump, you may want to first dump the database and then execute the DBCC statements to ensure that the database was consistent at the time it was dumped.

If a database or transaction log that contains errors is dumped, the errors will still exist when the database is reloaded. Under some conditions, these errors can even prevent successful reloading.

There are two important reasons to run DBCC statements on a database when no users are currently using the database. First, because DBCC performs numerous checks on the data pages in the database, it can have a noticeable impact on performance if users are trying to query the database while DBCC is running. Second, if users are actively updating the database while DBCC is running, it might report spurious errors, which can be misleading.

Note Starting with SQL Server 6.5 SP2, DBCC NEWALLOC will not report spurious errors, even if the database is in use. Prior to SQL Server 6.5 SP2, DBCC NEWALLOC is known to be susceptible to spurious errors if the database is in use.

For databases with a large amount of data (for example, in excess of 5 GB), the DBCC statements may take several hours to run, which can hamper the feasibility of running DBCCs on a production server. SQL Server on Windows NT–based computers addresses this by including the no_index option with DBCC statements. When using the no_index option, SQL Server checks only the consistency of the data pages and clustered index pages for each user table, not the nonclustered index pages, which can dramatically reduce the time necessary to execute DBCC statements. It is still advisable, however, to periodically execute full DBCC statements on the database to ensure consistency of the nonclustered indexes as well. The syntax for this option is to include the no_index keyword after the DBCC statement. For example, to perform all the consistency checks on the data pages but skip the checks on any nonclustered indexes, enter the following:

DBCC CHECKDB (pubs, no_index)
DBCC CHECKTABLE (inventory, no_index)

You can create Transact-SQL scripts containing DBCCs and use the Database Maintenance Wizard to schedule these scripts to run during periods of low activity.

Another solution to running DBCCs on large amounts of production data is to have a backup server running. In this configuration, database and transaction logs can be dumped from the production server and loaded onto the backup server. The DBCCs can then be run on the backup server without negatively affecting the performance of the production server. This is also a good safety net in the event that a hardware failure or other failure causes the production server to become unavailable for a long period of time. In this case, the backup server can quickly become the new production server, resulting in very little disturbance to users. The rapidly declining cost of PC hardware makes this option much more feasible than with earlier mini/mainframe platforms.

Occasionally, when dumping a database, you will receive SQL Server error 3004, stating:

%ld uninitialized pages encountered while dumping database %.*s. Run DBCC CHECKALLOC on this database for more information, then call technical support if there are any errors.

This error occurs if a problem is detected while doing an online dump. The dump procedure takes a snapshot of the database in order to begin the dump. Because some transactions may have allocated pages but not yet initialized them at the time the snapshot was taken, the dump procedure raises this informational message simply as a precaution.

If you encounter this message, rather than running DBCC CHECKALLOC, run DBCC NEWALLOC on that database, ensuring that no users are currently using the database while DBCC is executing.

Note In SQL Server 6.5, NEWALLOC has replaced the functionality of CHECKALLOC.

Under most circumstances, NEWALLOC will not return any errors, and the previous 3004 error can safely be ignored. If NEWALLOC does report other errors, however, you should contact your primary support provider for further instructions.


Loading Database Dumps

You need to consider several things when loading a database from a dump. First, the target database needs to be at least as large as the database that was dumped. Attempting to load a dump into a database that is smaller than the database that the dump came from will result in SQL Server error message 3105:

Data on dump will not fit into current database. Need %ld Mbyte database.

You can, however, load a dump into a target database that is larger than the original database.

Also consider whether the database will be loaded on the same server from which it was dumped, or if it may potentially be loaded onto a different server. If the database will be dumped and loaded between servers, the code page, sort order, and processor architecture between the servers must match. You cannot load a database onto a SQL Server running with a code page or sort order that is different from the code page or sort order used on the SQL Server from which the dump originated. SQL Enterprise Manager includes a transfer management interface that you can use to transfer some or all objects from one database to another. This is useful when the servers are using different sort orders or code pages, or when they are using different hardware architectures—for example, Intel-based hardware and RISC-based hardware. If your environment has multiple SQL Servers, it is recommended that they all be configured with the same code page and sort orders.

If a database needs to be re-created and loaded from a previous dump, it is important that the database be re-created in exactly the same way that it was originally created. That is, the device usage, log space allocation, and segment definitions in the new database must be identical to the way they were when the database was dumped. This information is kept in the sysusages table in the master database, so you should always dump the master database whenever a change to a database is made that records anything in the master database.

Note If you upgraded the master database from SQL Server 4.21a, with a default size of 15 MB, to SQL Server 6.0, with a default size of 23 MB, it is recommended that you make a file-level backup of Master.dat.

In addition, if you save the scripts you use to create the initial database, re-creating the database will only require rerunning of those scripts. If a dump is loaded into a database that has data, log, or segment mappings that are different from the original database, DBCC NEWALLOC may report SQL Server error 2558:

Extent not within segment: Object %ld, indid %d includes extents on allocation page %ld which is not in segment %d.

This error can indicate that there are data pages allocated in portions of the database intended for log pages, or log pages allocated in portions that are intended for data. In the first case, the effect is that less space is available for the transaction log to grow. The second case is less serious because the data space being used by log pages will eventually become available when the log is truncated with the DUMP TRANSACTION statement.


Transaction Log Dumping and Loading

SQL Server's ability to perform online incremental backups, called transaction log dumps, provides an effective mechanism for up-to-the-minute recovery of data. If your environment will be implementing both database and transaction log dumps as a means of backup, it is important to have a well-planned procedure in place and tested before going into production.


Creating and Sizing Transaction Logs

To dump a transaction log to a physical dump device, the log must reside on its own device. This can be accomplished in one of two ways:

  • Use the LOG ON clause of the CREATE DATABASE statement when the database is initially created.

Or

  • After the database has been created:

    Use the ALTER DATABASE statement to change to a new device.

    Execute the sp_logdevice system procedure to move the log to the new device.

Ideally, every database should have its log on a separate device. Exceptions are small databases that are either dumped often enough to negate the need for transaction log dumps, or "test" databases whose contents are not needed or can be easily rebuilt, such as the pubs database. The other exception is the master database, which must have the data and log portions on the master device.

The first step in managing transaction logs is to estimate how large to make the log. The size will depend on the volume of transactions in the database and the frequency with which the log is dumped. After a transaction log is dumped to a physical dump device, the inactive portion of the log—the portion from the beginning of the log to the first noncommitted transaction—is automatically truncated to free new space for the log to use. As a general rule, creating a log that is approximately 10 to 25 percent of the size of the database is a good place to start—depending on your environment, you may require a log that is significantly larger or smaller than that amount. It is best to simulate the volume and types of transactions that will be expected when the system is in production. If the log fills up or comes close to filling up before the scheduled transaction log dump occurs, you should either enlarge the size of the log or decrease the time between transaction log dumps.


Frequency of Transaction Log Dumps

When deciding how frequently to dump the transaction log between database dumps, there are a couple of important points to consider. In the following example, assume a production application dumps its database at midnight every Friday, and transaction log dumps are performed every hour from 8 A.M. to 5 P.M. Monday through Friday, that is, 10 log dumps a day. If a failure occurs at 4:30 P.M. on Friday, resulting in the need to recover from backups, the previous Friday's database dump would need to be loaded, followed by 49 transaction log loads.

Although doing online log dumps results in a smaller performance hit to the SQL Server compared to database dumps, loading that many transaction logs can take a significant amount of time, resulting in a longer period of downtime. A better approach is to perform nightly database dumps and still perform hourly transaction log dumps during the day. Assuming the same scenario of a failure at 4:30 P.M. Friday, only Thursday night's database dump would need to be loaded, followed by the 9 hourly transaction log dumps from 8 A.M. through 4 P.M. on Friday.

Also consider that the larger the number of log dumps, the greater the risk of something happening to one of them. If any one transaction log dump is misplaced, deleted, or the transaction log truncated, no further transaction logs past that point can be loaded. Think of individual transaction logs as the pairs of teeth in a zipper. If one set of teeth is missing, you can only zip the zipper up to that point. Likewise, you can't skip over a missing transaction log.


Transaction Log Sequencing

SQL Server keeps track of the order of transaction log dumps by using a method that can be thought of as similar to a sequence number. The sequence number is incremented every time a DUMP TRANSACTION statement is issued, regardless of whether the log is being dumped to a physical dump device, or whether it is being truncated by using either the WITH TRUNCATE_ONLY or WITH NO_LOG clauses. When you restore transaction logs, they must be loaded in the same order in which they were dumped, and their sequence numbers must increase monotonically.

In the following example, assume that a database is dumped at midnight each night, and transaction log dumps are performed every hour from 8 A.M. to 5 P.M. The 8 A.M. dump would have a sequence number of 1, the 9 A.M. dump would have a sequence number of 2, and so on. Suppose that the transaction log completely fills up at 9:30 A.M. and that it must be dumped or truncated using the WITH NO_LOG option and that the remaining hourly dumps continue as scheduled. If the hard disk fails at 3 P.M. that day, the previous night's database dump could be loaded, followed by the 8 A.M., sequence number 1, and 9 A.M., sequence number 2, transaction log dumps.

However, attempting to load the 10 A.M. log dump would result in SQL Server error 4305:

Specified file 'dumpfile' is out of sequence. Current time stamp is 'some_date_and_time' while dump was from 'some_other_date_and_time'.

Error 4305 would be encountered because the 9:30 A.M. truncation of the log would have been given a sequence number of 3, and the 10 A.M. dump has a sequence number of 4. Since the truncation of the log does not produce a physical dump file, it cannot be loaded. The net effect is an attempt to go from sequence number 2 to sequence number 4, which, as stated earlier, is prohibited because the sequence numbers must increase monotonically. Therefore, the transactions that took place after 9 A.M. cannot be recovered. To avoid this situation, it is imperative that a full database dump be issued immediately after the transaction log is truncated, so that the sequence number in the database is reset.


Effect of "trunc. log on chkpt." on Transaction Logs

Two database options have an important affect on transaction logs: trunc. log on chkpt. and select into/bulkcopy. The trunc. log on chkpt. option automatically performs a DUMP TRANSACTION database WITH TRUNCATE_ONLY statement every time the SQL Server checkpoint handler wakes up. When trunc. log on chkpt. is set, the checkpoint handler wakes up once a minute for that database. Setting this option for a database is useful primarily in a development environment when backups of the transaction log are not wanted.

Note It is recommended that you use the lazy writer instead of the trunc. log on chkpt. option to flush out batches of dirty, aged buffers and make them available to user processes by placing them in the free buffer pool. (Buffers are considered dirty when they contain changes that must be written back to disk before the buffer can be reused for a different page.)

The lazy writer eliminates the need to checkpoint frequently for the purpose of creating available buffers. Frequent checkpointing creates a drag on server performance.

For more information about the lazy writer, see the Microsoft SQL Server documentation.

When trunc. log on chkpt. is set, you can rely only on recovering from your database dumps, not from your log dumps. When this option is set, SQL Server prohibits a transaction log dump to a physical dump device¾attempting to do so will yield SQL Server error 4208:

DUMP TRANsaction is not allowed while the trunc. log on chkpt. option is enabled: use DUMP DATABASE, or disable the option with sp_dboption.

You will need to dump the entire database after turning off the option. Although subsequent transaction log dumps to physical dump devices are allowed once the option is turned off, you must first dump the entire database before dumping any new transaction logs. Transaction log dumps performed before the database was dumped are not recoverable because the sequence number for the database will have already been incremented for as many times as the checkpoint handler truncated the log.

The following example illustrates the affects of the trunc. log on chkpt. option. Assume that a database was dumped at midnight, the transaction log was dumped to a physical device at 8 A.M., and at 8:15 A.M., the trunc. log on chkpt. option was set for the database. At 8:45 A.M., the option was turned off, and at 9 A.M., the log was successfully dumped to another dump device. Between 8:15 A.M. and 8:45 A.M., there may have been as many as 30 automatic truncations of the transaction log—one truncation each time the checkpoint handler woke up. If this database later needed to be restored, the database dump could be loaded, followed by the 8 A.M. transaction log dump. However, attempting to load the 9 A.M. log dump would result in SQL Server error 4305 because the log had been truncated several times between 8:15 A.M. and 8:45 A.M. while the trunc. log on chkpt. option was set. Therefore, if you need to rely on your transaction log dumps for recovery, you must dump the database after turning off the trunc. log on chkpt. option or future log dumps will not be recoverable.

For databases that do not have the log on a separate device, there is no harm in having the trunc. log on chkpt. option set. If the log is located on the same device as the data, SQL Server disallows the dumping of the transaction log to a physical device—only DUMP DATABASE is allowed for backing up—so sequencing of the transaction log is not an issue.


Effect of "select into/bulkcopy" on Transaction Logs

The select into/bulkcopy option must be set in a database when you want to do nonlogged operations such as SELECT INTO or fast bulk copy using the bulk copy program.

Note Nonlogged operations require a full database dump. Transaction log dumps are not allowed, since nonlogged operations, by definition, don't appear in the transaction log.


Dumping a Full Transaction Log

It is possible for a transaction log to become so full that there is no room left to log new transactions. When this occurs, SQL Server reports error 1105:

Can't allocate space for object 'syslogs' in database database_name because the 'logsegment' segment is full. If you ran out of space in Syslogs, dump the transaction log. Otherwise, use ALTER DATABASE or sp_extendsegment to increase the size of the segment.

In most cases, the log can be dumped to a physical dump device, which will free up new space in the log. When the transaction log is dumped, SQL Server first writes a checkpoint record in the log to get a snapshot of which transactions are currently open. It then writes out the pages of the log and removes the inactive portion of the log.

If the log is so full that there is not even enough room left to write the checkpoint record, the only option available is to issue a DUMP TRANSACTION database_name WITH NO_LOG statement. This statement truncates the inactive portion of the log without writing the initial checkpoint record and without logging any of the truncation operation. Because the log is not written to a physical dump device, it is not recoverable. It is therefore imperative that the database be dumped immediately so that future transaction log dumps will be recoverable. If you encounter this situation regularly, you should increase the size of the log or increase the frequency of your log dumps.

SQL Server can help prevent a transaction log from ever filling completely. Through its close integration with the Windows NT Performance Monitor, the percentage of log space used for each database can be continuously monitored. Using Performance Monitor alerts, the database administrator can have Performance Monitor automatically run a batch file to dump the transaction log when the percentage of log space used hits a predefined threshold. Using this approach, along with the automated scheduled backup, alerting, and e-mail and page notification capabilities of SQL Enterprise Manager, the database administrator's task of managing backups is greatly simplified and automated.


Loading Transaction Logs

If a situation arises that requires you to recover from database and transaction log dumps, the load procedure needs to be completed in one continuous step. That is, the database should first be loaded, followed by each of the transaction logs, with no activity taking place in between each load. However, users can be actively doing updates in other databases. If any updates take place in the target database before all the logs have been loaded, when the next log load is attempted, SQL Server will raise error 4306:

There was activity on database since last load, unable to load. Must restart load sequence with the load database to continue.

As the message indicates, you must start back at the beginning by loading the database dump, followed by all the log dumps. For this reason, it is often advisable to start SQL Server in single-user mode when loading a database. In single-user mode, only one user at a time is allowed access to SQL Server.

Alternatively, SQL Server could be started normally, but SQL Enterprise Manager or sp_dboption could be used to turn on the single user option for the database being loaded. This allows users to freely access other databases on the server but allows only one person to access the database being loaded.

Caution Shutting down and restarting SQL Server during a load sequence can lead to error 4306 because the SHUTDOWN statement puts a checkpoint record in each database and each database is checkpointed when SQL Server is restarted.


Managing a Backup Server

If a hard disk drive or other failure results in the computer being unusable for a while, it can be a relief to know you have reliable backups of your data. However, making the necessary repairs and reloading the dumps of the database and logs can take considerable time. A very cost-effective alternative to this is to maintain a "warm" backup server at all times.

SQL Server includes features that make it very easy to have another server standing by in case something should happen to the primary production server. Assume that you have two servers:

  • Primary is the primary production SQL Server.
  • Standby is another server on the network, also running SQL Server, with devices, databases, and user accounts set up identically to those on Primary.

Each time a database is dumped from Primary, you will immediately load it onto Standby. Likewise, you will immediately load each transaction log dump from Primary onto Standby. It is recommended, as an additional precaution, that these dumps also be copied to tape or some other medium and stored. Should a problem arise on Primary that will require significant downtime, Primary can be taken offline, and Standby's server name changed to Primary. Using this approach, the only downtime will be the few minutes necessary to take Primary offline and change Standby's name. No user applications will need to change, and the data on the server will be current through the last transaction log dump made from the old Primary server.


Setting Up a Backup Server

To accomplish a backup server setup, there are a couple of changes that need to be made to the databases on Standby. After initially creating the databases on Standby, the two database options read only and no chkpt on recovery need to be set for each database that will be maintained. As stated earlier, when loading a database and its transaction logs, no update activity can take place in the database until all logs have been loaded. These two options help to reduce the risk of having any activity between log loads. When SQL Server is started, a checkpoint record is written in each database after it has been recovered. Setting the no chkpt on recovery option prevents SQL Server from writing this checkpoint. That way, if the Standby server goes down and SQL Server is restarted, the databases will still show that no activity has taken place, and transaction logs can continue to be loaded from the Primary server.

If SQL Server is manually stopped by using the SHUTDOWN statement, the shutdown procedure waits for all active processes to complete and checkpoints each database before stopping. The writing of this checkpoint prevents any further transaction log loads because there would have been an update made to the database. Setting the read only option not only prevents users from performing any write activity in a database but also causes SQL Server to bypass writing a checkpoint record in the database when a SHUTDOWN statement is issued. When these two options are set for the databases on Standby, database and transaction logs should be able to continue loading regardless of how the Standby server goes down. If the Standby server is needed to replace Primary, you must turn off the no chkpt on recovery and read only options before users can resume updating.


Integrating Database-Web Connectivity

Microsoft offers several tools you can use to integrate databases with your intranet content.

Companies choosing to adopt World Wide Web technology need to integrate it with their existing information technologies, such as databases. Web-database integration software helps Webmasters and database administrators solve two business problems:

  • Publishing snapshots of database information on a Web page
  • Using a Web browser as a database front end

Microsoft has created Web-database integration tools to help you solve these problems. Choose the combination that works best for you.

You must use the special license pack, SQL Server Internet Connector, when integrating a Web server with Microsoft SQL Server. For more information, see the "Microsoft SQL Server Internet Connector" section, later in this article.


Publishing Snapshots of Database Information

Sometimes you may need to make available to many individuals in your organization information stored in your SQL Server databases. These individuals may not have the appropriate client-side applications installed. A logical solution to this dilemma is to extract information from the database and publish it on your company intranet.

In this type of situation, the data owner or database administrator determines what information to publish, and when to publish it. Users need to view database information, but don't need to alter database records. The results of one query or report are published to many people to save the time of running the query again and again, to reduce the risk of running the wrong query, or to reduce the performance impact that multiple queries would have on the database server.

Microsoft makes three products that address this issue:

  • SQL Workbook Publisher
  • The Web Wizard component of Microsoft Access 97
  • The SQL Server Web Assistant component of Microsoft SQL Server 6.5

Each extends Microsoft's database software by effectively converting query results into HTML pages. Each creates Web pages that any Web server can publish and any Web client can browse.

Note If you have not yet upgraded to Microsoft Access 97, you can download Internet Assistant for Microsoft Access 95 from the Microsoft Web site at http://www.microsoft.com.

Answer these questions to choose the right tool for your needs:

Do you need the Web page to update automatically?

  • If yes, use Web Assistant.
  • Microsoft Access solutions require that you run Microsoft Access interactively. SQL Workbook Publisher requires that you run Microsoft Excel interactively.

Is the ODBC data source Microsoft SQL Server?

  • If yes, use Web Assistant or SQL Workbook Publisher.
  • If no, use a Microsoft Access solution.

Do you want to leverage investments in Microsoft SQL Server, Microsoft Access, or Microsoft Excel 8.0?

  • Web Assistant is supplied with and requires Microsoft SQL Server 6.5.
  • The Web Wizard is supplied with and requires Microsoft Access solutions. Internet Assistant is a no-charge add-in product that runs only with Microsoft Access 95.
  • SQL Workbook Publisher is a no-charge add-in product that runs with Microsoft SQL Server 6.5 and Microsoft Excel 8.0.

Is the Web server an Internet Information Server (IIS)?

  • If yes, the IIS add-in for Microsoft Access can be used in place of the Microsoft Access solutions.


Publishing with Microsoft Access

The following illustration shows how users access a database with the Microsoft Access Web Wizard. It is assumed that Microsoft Access 97 is already installed.

Use Microsoft Access 97 to make queries or reports to track your data.

On the File menu in Microsoft Access 97, click Save As HTML.

Proceed through each screen of the Web Wizard.


Publishing with SQL Server Web Assistant

The following illustration shows how users access a database with SQL Server Web Assistant. It is assumed that SQL Server 6.5 is already installed.

Start SQL Server Web Assistant either on the server or on a 32-bit SQL Server client.

(The illustration shows the simpler, less common case in which the SQL Server Web Assistant runs on the server.)

Proceed through each wizard-like screen, making sure to schedule data refresh times.

At the specified scheduled time or data change instance, SQL Server executes the query and updates the old HTML file with the converted data. At this point, the HTML file can be viewed with a Web browser.


Publishing with SQL Workbook Publisher

SQL Workbook Publisher is a Microsoft Excel 97 add-in that makes it easy for users to easily analyze data stored in SQL Server databases. Users create workbooks that can be populated with data from SQL Server databases. SQL Workbook Publisher enables these workbooks to be saved to SQL Server databases, where they can be shared with many people within an organization. With a few mouse clicks, users can obtain data stored in a SQL Server database in a formatted Excel workbook.

You can install SQL Workbook Publisher on your Microsoft Internet Information Server to enable users to browse workbooks saved on SQL Server from your corporate Intranet. With Microsoft Internet Explorer, users can view existing workbooks saved on one or more SQL Workbook Publisher–enabled servers.

SQL Workbook Publisher is included on the BackOffice Resource Kit CD-ROM, along with detailed documentation about its usage.


Using a Browser as a Database Front End

The two-fold challenge of frequently changing data and heavy demand for information becomes even more complex when many users don't have time to install and learn custom database applications. Management of data can be streamlined if you empower users to interact with the database on their terms, that is, with Web browsers.

In this type of situation, users need such a variety of information, or the information changes so rapidly, that you can't feasibly extract and publish it as snapshots. Additionally, users need to update, as well as view, database records.

You can use the Internet Database Connector (IDC) component of Internet Information Server (IIS). This extends Microsoft Web server software by providing links between IIS and any ODBC data source. It requires Windows NT Server 3.51 SP4 or later, and works with any Web browser software.

Note Another tool, Visual FoxPro™ WWW Search Page Wizard, is available from the Microsoft Web site (version 4 product) or is supplied with the version 5 product. This tool is not discussed here because it is not a SQL Server solution.

The following illustration shows how users access a database with IDC.

From the BackOffice Resource Kit CD-ROM install IIS on a Windows NT Server computer.

Use a text editor to create two files: an .htx file and an .idc file.

An .htx file contains HTML code that will be merged with the results of database queries. An .idc file contains the name of the ODBC data source that contains the data you want to make accessible, SQL statements that extract information or update records, and a reference to the .htx file.

Add a link that references the .idc file to an existing Web page.

When a user selects this link, IIS notifies IDC. IDC checks the appropriate .idc file to locate the ODBC data source, sends the SQL statements, and receives the results. IDC merges the results with the .htx file to create a new Web page, and IIS sends the new page to the browser.


Microsoft SQL Server Internet Connector

The SQL Server Internet Connector is an add-on product that allows an unlimited number of Internet and intranet connections to a single SQL Server. You must purchase a license pack called the Microsoft SQL Server Internet Connector to legally use Microsoft SQL Server with a Web server. This is required regardless of whether the Web server is IIS or a third-party product, whether the Web server runs on Windows NT Server or another operating system, whether the Web server is on the Internet or your company intranet, or whether the access is performed by a service like IDC or dbWeb, or by other methods, such as Common Gateway Interface (CGI) scripts.

A single SQL Server Internet Connector applies to one SQL Server only; it is a one-to-one relationship. It permits an unlimited number of computers or workstations to access the services of a single server running Microsoft SQL Server. You don't need to acquire a separate Client Access License for each computer or workstation, provided access to the server is available only through a Web server. An unlimited number of Web servers can legally access any single SQL Server that has SQL Server Internet Connector.

With the purchase of the SQL Server Internet Connector and the appropriate number of Client Access Licenses, any single SQL Server can simultaneously support Internet user access and standard client/server access. The purchase of Client Access Licenses is independent of the purchase of the SQL Server Internet Connector. Client Access Licenses are always required for each concurrent client/server user. The SQL Server Internet Connector is a special license for database connections through a Web server only.


Optimizing Queries

These suggestions for improving your query processing are offered by Microsoft SQL Server product specialists.

Each of the following sections offers tips to speed query processing:

  • Database Design
  • Quick Tips From the Experts
  • Query and Index Design
  • Query and Index Tuning
  • Using UPDATE in SQL Server 6.5
  • ANSI Options in Procedures and Triggers


Database Design

Intelligent database design is perhaps the most critical element of an optimal SQL Server solution with respect to performance. In fact, poor design is usually the culprit for poorly performing SQL Server solutions. This section discusses critical design factors that must be considered to produce an efficient, logical database design. It is assumed you are familiar with relational database design concepts such as entity-relationship modeling and normalization.


Logical Database Design

Designing an optimal relational database is typically accomplished by using entity-relationship modeling and normalization. These two processes or methodologies aid in defining the logical data model.

Entity-relationship modeling is the identification of data entities or objects and the relationships between these entities. The entity-relationship modeling process usually progresses in the following manner:

Entities or objects are identified.

Identifiers or primary keys that uniquely identify each entity are identified.

Data elements or attributes associated with each entity are identified.

Relationships between entities are identified, thereby resulting in the identification of primary key/foreign key relationships.

Having completed this process, the resulting entity-relationship model now represents a logical view of the data entities and associated relationships upon which the physical database design will be based. Furthermore, it is during this modeling process that normalization commonly occurs.

Generally, a logical database design will satisfy the first three levels of normalization as follows:

  • First Normal Form: You cannot have repeating groups or multivalue columns.
  • Second Normal Form: Every nonkey field must depend on the entire primary key and not on the constituent parts of a composite primary key.
  • Third Normal Form: A nonkey field must not depend on another nonkey field.

In essence, a design based on these rules yields a greater number of narrow tables, thereby reducing data redundancy and decreasing the number of pages required to store the data. Consequently, table relationships may need to be resolved by using complex joins. However, the SQL Server optimizer is designed to take advantage of normalized logical database designs, as long as efficient indexes have been derived from the identified primary key/foreign key relationships. Nonetheless, there are trade-offs between a highly normalized database design and an intelligently denormalized design. It is this strategy of selective and intelligent denormalization that will most often result in the greatest performance gains as related to logical database design.


SQL Server Denormalization Tactics and Benefits

In some cases, you may want to denormalize the database model. Targeted denormalization of specific tables can improve performance. Denormalization may take place at the entity or attribute level, and therefore requires a knowledge, as previously discussed, of how the data will be accessed and used. Denormalization may be accomplished in many different ways based upon myriad performance considerations. However, the following tactics have proven useful for improving performance.

Introduce Redundancy

If the normalized design results in many 4-way or greater join relationships, consider introducing redundancy at the attribute (column) or entity (table) level as follows:

  • Add duplicate attributes (columns) to the database entities (tables).
  • Add derived attributes (columns) to the database entities (tables)—for example, aggregates, maximum values, and so on.

Redefine Attributes

Redefine attributes to reduce the data width of an entity as follows:

  • Add contrived attributes (columns) to the database entities (tables).

    Appropriate attribute candidates are large keys and text fields. Therefore, a multiattribute key on which many joins will take place can be replaced with a smaller contrived key. A text field can be redefined or augmented by an abstract field of 255 characters or less.

Redefine Entities

Redefine entities (tables) to reduce the overhead of extraneous attribute (column) data or row data. Appropriate types of associated denormalization are:

  • Segment an entity (table) by attributes (columns) into two entities (tables), separating high-access data from low-access data.

    This scenario requires that the primary key be duplicated in each new table. Such a design may help with concurrency and results in narrower tables.

  • Segment an entity (table) by rows into two entities (tables).

    This scenario works well on entities (tables) with the potential for large data volumes. This is also a good tactic if data rows are accessed as subsets by logical workgroups (department, market segment, geography, and so on). Additionally, if a subset of the larger data set is the most active, the subset is a candidate for segmentation.


Database Design Strategy Summary

The goal is to develop as optimal a logical database design as possible, before physical implementation of the database, to minimize database tuning during later stages of the SQL Server solution development process. To attain this goal, you must apply your knowledge of the user and application requirements to efficiently balance between a normalized and denormalized data model. The end result should save space and time with regard to performance. Therefore, when creating physical tables, remember that the data type associated with each table column should reflect the smallest storage necessary for the required data. This results in more data rows fitting on a single data page and therefore fewer I/Os.


Quick Tips from the Experts

To most effectively optimize Microsoft SQL Server performance, you must identify the areas that will yield the largest performance increases over the widest variety of situations and analyze these areas. Otherwise, you may expend significant time and effort on areas that may not yield sizable improvements.

This section focuses primarily on areas that years of experience by the Microsoft SQL Server Support team have shown to be of practical value in real-world situations.

Experience shows that the greatest benefit in SQL Server performance can be gained from the general areas of logical database design, index design, query design, and application design. Conversely, the biggest performance problems are often caused by deficiencies in these same areas. If you are concerned with performance, you should concentrate on these areas first because very large performance improvements can often be achieved with a relatively small time investment.

While other system-level performance issues, such as memory, cache buffers, hardware, and so forth, are certainly candidates for study, experience shows that the performance gain from these areas is often minimal. SQL Server manages available hardware resources automatically (for the most part), reducing the need, and therefore the benefit, of extensive, system-level hand tuning.

Microsoft SQL Server opens up opportunities for platform-layer performance improvements with large amounts of memory, symmetrical multiprocessing, parallel data scan, optimizer enhancements, and disk striping. However, as large as these improvements are, they are finite in scope. The fastest machine can be bogged down with inefficient queries or a poorly designed application. Therefore, even with the additional performance features of SQL Server, it is of paramount importance to optimize the database, index, query, and application design.

Most performance problems cannot be successfully resolved solely with a server-side focus. The server is essentially a "puppet" of the client, which controls what queries are sent and thereby what resources are obtained and released. Although some tuning is possible on the server side, successful resolution of performance problems usually depends on acknowledging the dominant role the client plays in the problem and analyzing client application behavior.

The following are some suggestions that, based on experience, have yielded significant performance gains.


Normalize Logical Database Design

Reasonable normalization of the logical database design yields the best performance. A greater number of narrow tables is a characteristic of a normalized database. A lesser number of wide tables is a characteristic of a denormalized database. A highly normalized database is routinely associated with complex relational joins, which can hurt performance. However, the SQL Server optimizer is efficient at selecting rapid, efficient joins, as long as effective indexes are available.

The benefits of normalization include:

  • Accelerated sorting and index creation, since tables are narrower.
  • More clustered indexes, since there are more tables.
  • Compact and narrow indexes.
  • Fewer indexes per table, improving UPDATE performance.
  • Fewer NULLs and less redundant data, increasing database compactness.
  • Reduced concurrency impact of DBCC diagnostics, since the necessary table locks will affect less data.

With SQL Server, reasonable normalization often helps rather than hinders performance. As normalization increases, so does the number and complexity of joins required to retrieve data. As a rough rule-of-thumb, extensive normalization is recommended unless it causes many queries to join in excess of four ways.

If the logical database design is already fixed and total redesign is not feasible, it may be possible to selectively normalize a large table if analysis shows a bottleneck on this table. If access to the database is conducted through stored procedures, this schema change could take place without impacting applications. If not, it may be possible to hide the change by creating a view that presents the illusion of a single table.


Use Efficient Index Design

Unlike many nonrelational systems, relational indexes are not considered part of the logical database design. Indexes can be dropped, added, and changed without impacting the database schema or application design in any way other than performance. Efficient index design is paramount to achieving good SQL Server performance. For these reasons, you should not hesitate to experiment with different indexes.

The optimizer reliably chooses the most effective index in the majority of cases. The overall index design strategy should be to provide a good selection of indexes to the optimizer, and trust it to make the right decision. This reduces analysis time and gives good performance over a wide variety of situations.

The following are index design recommendations:

  • Examine the FROM and WHERE clauses of your SQL queries because this is the primary focus of the optimizer.

    Each column listed in the WHERE clause or in the JOIN portions of the FROM clause is a possible candidate for an index. If you have too many queries to examine, pick a representative set or just the slow ones. If your development tool transparently generates SQL code, this is more difficult. Many of these tools allow the logging of the generated SQL syntax to a file or screen for debugging purposes. You may want to find out from the tool vendor if such a feature is available or use SQL Trace to capture the SQL syntax on the server side.

  • Use narrow indexes.

    Narrow indexes are often more effective than multicolumn, compound indexes. Narrow indexes have more rows per page and fewer index levels, which improves performance. The SQL Server optimizer maintains distribution statistics on all prefix sets of a compound index. Therefore, if the first column or columns of a compound index have poor selectivity, the optimizer may not use the index.

    The optimizer can rapidly and effectively analyze hundreds or even thousands of index and join possibilities. Having a greater number of narrow indexes provides the optimizer with more possibilities to choose from, which usually helps performance. Having a lesser number of wide, multicolumn indexes provides the optimizer with fewer possibilities to choose from, which may hurt performance.

    It is often best not to adopt a strategy of emphasizing a fully covered query. It is true that if all columns in your SELECT statement are covered by a nonclustered index, the optimizer can recognize this and provide excellent performance. However, this often results in excessively wide indexes and stakes too much on the hope that the optimizer will use this strategy. Usually, you should use more numerous narrow indexes, which often provide better performance over a wider range of queries.

    You should not have more indexes than are necessary to achieve adequate read performance because of the overhead involved in updating those indexes. However, even most update-oriented operations require far more reading than writing. Therefore, do not hesitate to try a new index if you think it will help; you can always drop it later.

  • Use clustered indexes.

    Appropriate use of clustered indexes can tremendously increase performance. Even UPDATE and DELETE operations are often accelerated by clustered indexes, since these operations require much reading. You can only have a single clustered index per table, so use this index wisely. Queries that return numerous rows or queries involving a range of values are good candidates for acceleration by a clustered index.

    Examples:

SELECT * FROM PHONEBOOK

WHERE LASTNAME='SMITH'

Or

SELECT * FROM MEMBERTABLE

WHERE MEMBER_NO > 5000

AND MEMBER_NO < 6000

By contrast, the LASTNAME or MEMBER_NO columns mentioned above are probably not good candidates for a nonclustered index if this type of query were common. Try to use nonclustered indexes on columns where few rows are returned.

  • Examine column uniqueness.

    This helps you decide what column is a candidate for a clustered index, nonclustered index, or no index.

    The following example query allows you to examine column uniqueness:

SELECT COUNT (DISTINCT COLNAME), COUNT(*)

FROM TABLENAME

This returns the number of unique values in the column and the total number of rows. Compare these values. On a 10,000-row table, 5,000 unique values would make the column a good candidate for a nonclustered index. On the same table, 20 unique values would better suit a clustered index. Three unique values should not be indexed at all. These are only examples, not hard-and-fast rules. Remember to place the indexes on the individual columns listed in the WHERE and FROM clauses of the queries.

  • Examine data distribution in indexed columns.

    A long-running query often is caused by indexing a column with few unique values or performing a JOIN on such a column. This is a fundamental problem with the data and query itself and cannot usually be resolved without identifying this situation. For example, a physical telephone directory sorted alphabetically on last name will not expedite looking up a person if all people in the city are named just SMITH or JONES. In addition to the above query, which gives a single figure for column uniqueness, you can use a GROUP BY query to see the data distribution of the indexed key values. This provides a higher resolution picture of the data, and a better perspective for how the optimizer views the data.

    The following example query allows you to examine data distribution of indexed key values, assuming a two-column key on COL1 and COL2.

SELECT COL1, COL2, COUNT(*)

FROM TABLENAME

GROUP BY COL1, COL2

This returns one row for each key value along with a count of the instances of each value. To reduce the number of rows returned, it may be helpful to exclude some with a HAVING clause. For example, to exclude all rows that have a unique key, use the following HAVING clause:

HAVING COUNT(*) > 1

The number of rows returned in a query is also an important factor in index selection. The optimizer considers a nonclustered index to cost at least one page I/O per returned row. At this rate, it quickly becomes more efficient to scan the entire table. This is another reason to restrict the size of the result set or to locate a large result set with a clustered index.

Do not always equate index usage with good performance, and vice versa. If using an index always produced the best performance, the optimizer's job would be simple—always use any available index. In reality, incorrect choice of indexed retrieval can result in poor performance. Therefore, the optimizer's task is to select indexed retrieval where it will help performance and avoid indexed retrieval where it will hurt performance.


Use Efficient Query Design

Some types of queries are inherently resource intensive. This is related to fundamental database and index issues common to most RDBMSs, not to SQL Server in particular. They are not inefficient because the optimizer will implement the queries in the most efficient fashion possible. However, they are resource intensive, and the set-oriented nature of SQL Server may make them appear inefficient. No degree of optimizer intelligence can eliminate the inherent resource cost of these constructs. They are intrinsically costly when compared to a more simple query. Although SQL Server will use the optimal access plan, this is limited by what is fundamentally possible.

The following conditions are typically present in resource-intensive queries:

  • Large result sets
  • IN, NOT IN, and OR queries
  • Highly nonunique WHERE clauses
  • != (not equal) comparison operators
  • Certain column functions, such as SUM and AVG
  • Expressions or data conversions in WHERE and FROM clauses
  • Local variables in WHERE and FROM clauses
  • Complex views with GROUP BY or ORDER BY

Various factors may necessitate the use of some of these query constructs. The impact of these is lessened if the optimizer can restrict the result set before applying the resource-intensive portion of the query as shown in the following table examples.

Resource intensive

Less resource intensive

SELECT SUM(SALARY) FROM TABLE
SELECT SUM(SALARY) FROM TABLE WHERE ZIP='98052'
SELECT * FROM TABLE WHERE
LNAME=@VAR
SELECT * FROM TABLE
WHERE LNAME=@VAR AND ZIP='98052'

In the first example, the SUM operation cannot be accelerated with an index. Each row must be read and summed. Assuming that there is an index on the zip column, the optimizer will likely use this to initially restrict the result set before applying the SUM. This can be much faster.

In the second example, the local variable is not resolved until run time. However, the optimizer cannot defer until run time the choice of access plan but must choose at compile time. Yet at compile time, when the access plan is built, the value of @VAR is not known and consequently cannot be used as input to index selection.

The illustrated technique for improvement involves restricting the result set with an AND clause. An optional technique would be to use a stored procedure and pass as a parameter to the stored procedure the value for @VAR. In some cases it's best to use a group of simple queries and use temp tables to store intermediate results rather than to use a single, complex query.

Large result sets are costly on most RDBMSs. You should try not to return a large result set to the client. It is much more efficient to restrict the size of the result set, since the database back end is much more efficient at performing this function. This also reduces network I/O and makes the application more responsive to deployment across slow, remote, communication links. It also improves concurrency-related performance as the application scales upward to more users.


Use Efficient Application Design

The role application design plays in SQL Server performance cannot be overstated. Rather than picturing the server in the dominant role, it's more accurate to picture the client as a controlling entity and the server as a puppet of the client. SQL Server is totally under the command of the client regarding the type of query, when the query will be submitted, and how the results will be processed. This in turn has a major effect on the type and duration of locks, amount of I/O and CPU load on the server, and performance.

For this reason, it's important to make the correct decisions during the application design phase. Even if you're using a turnkey application where changes to the client application seem impossible, this doesn't change the fundamental factors that affect performance—namely, that the client plays a dominant role and that many performance problems cannot be resolved without making client changes.

With a well-designed application, SQL Server is capable of supporting thousands of concurrent users. With a poorly-designed application, even the most powerful server platform can bog down with just a few users.

The following suggestions for client application design are known to improve SQL Server performance:

  • Use small result sets.

    Retrieving needlessly large result sets (say, thousands of rows) for browsing on the client adds CPU and network I/O load, makes the application less capable of remote use, and can limit multiuser scalability. It's better to design the application to prompt the user for sufficient input so that only queries that generate modest result sets are submitted. Application design techniques that help ensure a small result set include exercising control over wildcards when building queries, mandating certain input fields, and disallowing ad hoc queries.

  • Use dbcancel() correctly in DB-Library applications.

    All applications should allow cancellation of a query in progress. No application should force the user to reboot the client computer to cancel a query because this can lead to unresolvable performance problems.

    When dbcancel() is used, proper care should be exercised regarding transaction level. The same issues apply to ODBC applications, where the ODBC sqlcancel() call is used. For more information, see "Causes of the Transaction Log Filling Up" in SQL Server Books Online.

  • Always process all results to completion.

    Do not design an application or use a turnkey application that stops processing result set rows without canceling the query. Doing so will usually lead to blocking and slow performance.

  • Always implement a query time-out.

    Do not allow queries to run indefinitely. Make the appropriate DB-Library or ODBC calls to set a query time-out.

    With DB-Library, this is done with dbsettime(); with ODBC use SQLSetStmtOption().

  • Do not use an application development tool that does not allow explicit control over the SQL statements sent to the server.

    Do not use a tool that transparently generates SQL statements based on higher-level objects if it does not provide crucial features such as query cancellation, query time-out, and complete transactional control.

    It is often not possible to maintain good performance or to resolve a performance problem if the application independently generates "transparent SQL" because this doesn't allow explicit control over transactional and locking issues that are critical to the performance picture.

  • Do not intermix decision support and online transaction processing (OLTP) queries.


Techniques to Analyze Slow Performance

It may be tempting to address a performance problem solely by system-level, server-performance tuning—for example, how much memory, the type of file system, the number and type of processors, and so forth. The experience of Microsoft SQL Server Support indicates that most performance problems cannot be resolved this way. They must be addressed by analyzing the application, the queries the application is submitting to the database, and how these queries interact with the database schema.

Isolate the Query

First, isolate the query or queries that are slow. It often appears that an entire application is slow when actually only a few of the SQL queries are slow. It is usually not possible to resolve a performance problem without breaking the problem down and isolating the slow queries.

SQL Server 6.5 includes SQL Trace, which monitors and records database activity. SQL Trace can display all server activity in real-time or create filters that focus on the actions of particular users, applications, or host servers. SQL Trace can display any SQL statement or remote procedure call (RPC) that is sent to any Microsoft SQL Server 6.5 server.

If you have a development tool that transparently generates SQL, use any available diagnostic or debug mode of this tool to capture the generated SQL. In many cases, trace features are available, but they may not be openly documented. Contact technical support for your application to determine if a trace feature exists for monitoring the SQL statements generated by the application.

For application development tools that use Embedded SQL, isolating slow queries is much easier—the SQL is openly visible.

If your development tool or end-user application does not provide a trace feature, and you are not using SQL Server 6.5, there are several alternatives:

  • Use the 4032 trace flag.

    This will allow capture of the SQL statements sent to the server in the SQL error log.

  • Monitor the queries with a network analyzer, such as Microsoft Network Monitor, which is part of Systems Management Server (SMS).
  • For ODBC applications, use the ODBC Administrator to select tracing of ODBC calls. For more information about ODBC Administrator, see the ODBC documentation.
  • Use a third-party, client-side utility that intercepts the SQL at the DB-Library or ODBC layers. An example of this is SQL Inspector from Blue Lagoon Software.
  • Use SQLEye, an analysis tool provided as an example on the Microsoft TechNet CD-ROM. (Note that SQLEye is an unsupported tool.)

Test Query Performance

After the slow query is isolated, perform the following steps:

Run the suspected slow query in isolation, using a query tool such as ISQL/w, and verify that it is slow.

It is often best to run the query on the server computer itself by using ISQL/w and local pipes and redirect the output to a file. This helps eliminate complicating factors, such as network and screen I/O and application results buffering.

Use SET STATISTICS IO ON to examine the I/O consumed by the query.

Notice the count of logical page I/Os. The optimizer's goal is to minimize I/O count. Make a record of the logical I/O count. This forms a baseline against which to measure improvement. It is often more effective to focus exclusively on the STATISTICS IO output and experiment with different query and index types than to use SET SHOWPLAN ON. Interpreting and effectively applying the output of SHOWPLAN can require some study and can consume time that can be more effectively spent on empirical tests. If your performance problem is not fixed by these simple recommendations, you can use SHOWPLAN to more thoroughly investigate optimizer behavior.

If the query involves a view or stored procedure, extract the query from the view or stored procedure and run it separately.

This allows the access plan to change as you experiment with different indexes. It also helps localize the problem to the query itself, versus how the optimizer handles views or stored procedures. If the problem is not in the query itself but only occurs when it is run as part of a view or stored procedure, running the query by itself will help determine this.

Be aware of triggers on the involved tables that can transparently generate I/O as the trigger runs.

You should remove any triggers involved in a slow query. This helps determine if the problem is in the query itself or the trigger or view.

Examine the indexes of the tables used by the slow query. Use the previously listed techniques to determine if these are good indexes, and change them if necessary.

As a rough rule-of-thumb, try indexing each column in your WHERE or FROM clause. Performance problems are often caused simply by not having a column in the WHERE or FROM clause indexed or by not having a useful index on such a column.

Using the queries previously mentioned, examine the data uniqueness and distribution for each column mentioned in the WHERE or FROM clause, especially for each indexed column.

In many cases, simple inspection of the query, table, indexes, and data will immediately show the problem cause. For example, performance problems are often caused by having an index on a key with only three or four unique values, or performing a JOIN on such a column, or returning an excessive number of rows to the client.

Based on this study, make any needed changes to the application, query, or indexes. Run the query after making the change, and observe any change in I/O count.

After noting the improvement, run the main application to see if overall performance is better.

Check for I/O- vs. CPU-Bound Query Behavior

Check the program for I/O- or CPU-bound behavior. It is often useful to determine if a query is I/O- or CPU-bound. This helps focus your improvement efforts on the true bottleneck. For example, if a query is CPU bound, adding memory to SQL Server is not likely to improve performance because more memory only improves the cache hit ratio, which in this case, is already high.

To examine I/O-versus CPU-bound query behavior

  • Use Windows NT Performance Monitor to watch I/O versus CPU activity.
  • Watch all instances of the % Disk Time counter of the LogicalDisk object. Also watch the % Total Processor Time counter of the System object. (To see valid disk performance information, you must have previously turned on the Windows NT DISKPERF setting by issuing diskperf -y from a command prompt and then rebooting the system. For more information, see the Windows NT documentation.)
  • While running the query:
    • If the CPU graph is consistently high (say, greater than 70 percent) and the % Disk Time is consistently low, this indicates a CPU-bound state.
    • If the CPU graph is consistently low (say, less than 50 percent) and the % Disk Time is consistently high, this indicates an I/O-bound state.
  • Compare the CPU graph with the STATISTICS IO information.


Quick Tips Strategy Summary

SQL Server is capable of very high performance on large databases. To achieve this performance potential, you must use efficient database, index, query, and application design. These areas are the best candidates for obtaining significant performance improvement. Try to make each query as efficient as possible, so that when your application scales up to more users, the collective multiuser load is supportable. It is recommended that you study the client application behavior, the queries submitted by the application, and experiment with indexes using the guidelines in this document. A methodical approach in analyzing performance problems will often yield significant improvement for relatively little time investment.


Query and Index Design

With a solid database design implemented on the chosen hardware platform and with a knowledge of user expectations and applications, you are now prepared to design queries and indexes. There are two critical aspects to achieving query and index performance goals on SQL Server. The first is to create queries and indexes based on knowledge of the SQL Server optimizer. The second is to use SQL Server performance features that enhance data access operations.


The SQL Server Optimizer

The Microsoft SQL Server database engine uses a cost-based query optimizer to automatically optimize data manipulation queries that are submitted using SQL. A data manipulation query is any query that supports the WHERE or HAVING keywords in SQL, such as SELECT, DELETE, and UPDATE. The cost-based query optimizer produces cost estimates for a clause based on statistical information.

This optimization is accomplished in three phases:

  • Query analysis
  • Index selection
  • Join selection

Query Analysis

In the query analysis phase, the SQL Server optimizer looks at each clause represented by the canonical query tree and determines whether it can be optimized. SQL Server attempts to optimize clauses that limit a scan, such as search or join clauses. However, not all valid SQL syntax can be broken into optimizable clauses—for example, clauses containing the SQL relational operator <> (not equal to). Because <> is an exclusive rather than an inclusive operator, the selectivity of the clause cannot be determined before scanning the entire underlying table. When a relational query contains nonoptimizable clauses, the execution plan accesses these portions of the query using table scans. If the query tree contains any optimizable SQL syntax, the optimizer performs index selection for each of these clauses.

Index Selection

For each optimizable clause, the optimizer checks the database system tables to see if there is an associated index useful for accessing the data. An index is considered useful only if a prefix of the columns contained in the index exactly matches the columns in the clause of the query. This must be an exact match because an index is built based on the column order presented at creation time. For a clustered index, the underlying data is also sorted based on this index column order. Attempting to use only a secondary column of an index to access data would be similar to attempting to use a phone book to look up all the entries with a particular first name: The ordering would be of little use because you would still have to check every row to find all of the qualifying entries. If a useful index exists for a clause, the optimizer then attempts to determine the clause selectivity.

When cost-based optimization was previously mentioned, it was stated that a cost-based optimizer produces cost estimates for a clause based on statistical information. This statistical information is used to estimate a clause's selectivity (the percentage of tuples in a table that are returned for the clause). Microsoft SQL Server stores this statistical information in a specialized data distribution page associated with each index. This statistical information is updated only:

  • During the initial creation of the index, if data exists in the table.
  • Whenever the UPDATE STATISTICS statement is executed for either the index or the associated table.

To provide SQL Server with statistics that accurately reflect the actual tuple distribution of a populated table, the database system administrator must keep current the statistical information for the table indexes. If no statistical information is available for the index, a heuristic based on the relational operator of the clause is used to produce an estimate of selectivity.

Information about the selectivity of the clause and the type of index available is used to calculate a cost estimate for the clause. SQL Server estimates the amount of physical disk I/O that occurs if the index is used to retrieve the result set from the table. If this estimate is lower than the physical I/O cost of scanning the entire table, an access plan that employs the index is created.

Join Selection

When index selection is complete and all clauses have an associated processing cost based on their access plan, the optimizer performs join selection. Join selection is used to find an efficient order for combining the clause access plans. To accomplish this, the optimizer compares various orderings of the clauses and then selects the join plan with the lowest estimated processing costs in terms of physical disk I/O. Because the number of clause combinations can grow combinatorially as the complexity of a query increases, the SQL Server query optimizer uses tree pruning techniques to minimize the overhead associated with these comparisons. When this join selection phase is complete, the SQL Server query optimizer provides a cost-based query execution plan that takes advantage of available indexes (when they are useful) and accesses the underlying data in an order that minimizes system overhead and improves performance.


Efficient Query Design

Based on the information regarding the three phases of query optimization, it is obvious that designing queries that minimize physical and logical I/O as well as balance processor and I/O time is the goal of efficient query design. In essence, this means you want to design queries that result in the use of indexes, result in the fewest disk reads and writes, and make the most efficient use of memory and CPU resources.

The following guidelines, which are derived from the optimization strategies of the SQL Server optimizer, will aid in the design of efficient queries. However, before we can discuss the query design guidelines, a few definitions are necessary.

Definitions

Table Scan—A table scan occurs when the SQL Server optimizer can find no efficient index to satisfy a clause or when a clause is nonoptimizable. When the table scan method is used, execution begins with the first row in the table. Each row is retrieved and compared with the conditions in the WHERE clause and then returned to the client if it meets the given criteria. Regardless of how many rows qualify, every row in the table must be looked at; so for very large tables, a table scan can be costly in terms of page I/Os.

Worktable—For some types of queries, such as those that require the results to be ordered or displayed in groups, the SQL Server query optimizer might determine that it is necessary to create its own temporary worktable. The worktable holds the intermediate results of the query, at which time the results can be ordered or grouped, and then the final results can be selected from that worktable. When all results have been returned, the worktable is automatically dropped.

Worktables are always created in the tempdb database, so it is possible that the system administrator might have to increase the size of tempdb to accommodate queries that require very large worktables. Because the query optimizer creates these worktables for its own internal use, the names of the worktables will not be listed in the tempdb..sysobjects table.

Query Design Guidelines

Here are the guidelines:

  • WHERE clauses that direct index selection should be of the following form:

WHERE column operator constant AND expression

Or

WHERE constant operator column AND expression

where operator is =, >, >=, <, or =< and all columns are in the same table.

  • A WHERE clause with BETWEEN is treated as a closed interval in the form:

WHERE column BETWEEN constant AND constant

generates

WHERE (column >= constant AND column <= constant)

  • A WHERE clause with LIKE and a trailing wild card is treated as a closed interval in the form:

WHERE column LIKE constant%

generates

WHERE (column >= constant AND column < constant)

  • Expressions or data conversions in a WHERE clause are not likely to result in an index selection by the optimizer—for example:

paycheck * 12 > 36000

Or

substring(city,1,1) = "C"

  • WHERE clauses with the "=" operator result in the best performance if a unique index is available. Closed intervals (ranges) are next best; open intervals follow.
  • WHERE clauses that contain disjunctions (OR or IN) do not generally result in the best performance from a data-access perspective. Therefore, the optimizer can elect to use the "OR strategy." This strategy results in the creation of a worktable that contains row IDs for each possible matching row. The optimizer considers these row IDs (page number and row number) to be a "dynamic index" pointing to a table's matching rows. Accordingly, the optimizer scans the worktable, getting each row ID, and retrieves the corresponding rows from the data table. Consequently, the cost of the "OR strategy" is the creation of the worktable.

    The SQL Server optimizer elects to use the "OR strategy" based on the following conditions:

    • All columns of the OR clause must belong to the same table.
    • If any portion of the OR clause requires a table scan (due to lack of index or poor selectivity of a given index), a table scan will be used for the entire query.
    • If any other access plan will result in fewer I/Os (less cost), it will be used.
  • A WHERE clause containing NOT, <>, or != is not useful to the optimizer for index selection. This is due to the exclusive, rather than inclusive, nature of such clauses. Consequently, the selectivity of the clause cannot be determined before scanning the entire underlying table.
  • Local variables in WHERE clauses are considered to be unknown and are not considered by the optimizer. The exception to this are variables defined as the input parameters of stored procedures.
  • Limit data conversions and string manipulations because these are resource intensive, especially when applied to large data sets.
  • Worktables are created by the SQL Server optimizer as follows:
    • GROUP BY—Always requires a worktable.
    • ORDER BY—Only if an index is not available for index ordering or the available indexes are in conflict with the SQL Server "sort order."
    • SELECT INTO—Builds the worktable in the user database and not in tempdb unless instructed to do so.
    • DISTINCT—There is no need to use DISTINCT for columns that are covered by a unique index.
    • If no indexes that cover a join clause are found, a worktable is built to hold the rows from the smallest table in the join. A clustered index is then built on this table to accomplish an efficient join. Therefore, the cost is the generation of the worktable and the subsequent creation of the clustered index. This process is called reformatting.

Therefore, attention must be paid to the size of the tempdb database (except for SELECT INTO) whether in RAM or on disk. In addition, if these types of operations are common, placing tempdb in RAM can be beneficial to performance.

Concurrency and Consistency

The importance of understanding concurrency issues is paramount to the efficient execution of queries on multiuser SQL Server systems. Dealing with concurrency and consistency issues in database queries and applications is an example of needing to understand and balance conflicting objectives.

  • Concurrency—An attempt to maximize the number of simultaneous transactions, or users.
  • Consistency—The need to ensure that the operations performed by users in a multiuser environment are equivalent to the results that would be obtained if users ran their transactions serially.

These are competing requirements that need to be balanced against each other. SQL Server provides the means to ensure transaction consistency, or serializability, through locking. The most important concurrency guidelines to remember when designing efficient queries are as follows:

  • Avoid situations in which many processes are attempting to perform updates or inserts on the same data page. This can occur in a nonindexed table because all additions are applied to the last page in the chain. Creating separate history tables that are accessed by various groups can minimize the delay in this situation. Creating a clustered index to distribute data will also help.
  • Avoid transactions that include user interaction. Because locks are held for the duration of the transaction, a single user can degrade the entire system performance if the user does not respond in a timely manner.
  • Keep transactions that modify data as short as possible. The longer the transaction, the longer the exclusive or update lock is held. This blocks other activity and can lead to an increased number of deadlock situations.
  • Keep transactions in one batch. Unanticipated network problems can delay completion of transactions and releasing locks.
  • Use HOLDLOCK only when necessary because updates can be delayed by waiting for shared locks to be released.
  • To help diminish the chance of random updates requiring the same page, reduce the fill factor when creating an index. This is especially useful for small tables that are frequently accessed.
  • By using the SQL Server cursor extensions to DB-Library or ODBC, optimistic concurrency control can be specified. This is ideal for applications that require a high degree of user interaction combined with high concurrency. This option ensures that update locks are obtained only when a user wants to commit a transaction.
  • Avoid deadlocks. Deadlocks occur when user processes are competing for resources and a circular chain of dependency for locks results. SQL Server automatically detects deadlocks and ends one of the user transactions involved in the transaction. The user application must then resubmit the stopped query—a time consuming process. Some deadlocks are unavoidable, but many deadlocks can be avoided by acquiring resources in the same order.

    The following illustration shows how deadlocks can be unnecessarily introduced into an application when resources are not acquired in the same order.

Stored Procedures and Views

The following illustration gives a high-level overview of how stored procedures and Transact-SQL queries are handled by SQL Server.

When a stored procedure is created, the ASCII text of the stored procedure is stored in the syscomments table, and a normalized form of the query, called a query tree, is stored in the sysprocedures table. The query tree has already been parsed.

When a stored procedure is executed for the first time after SQL Server has been started, the query tree is brought into memory, passed through the query optimizer to create an access plan, and stored in the procedure cache. The access plan created on this first pass is used for all subsequent calls to this copy of the stored procedure.

Stored procedures are reusable, but not re-entrant; therefore, only one user can execute a given copy at a time. If two or more users execute a stored procedure at the same time, SQL Server loads two copies of the procedure into the procedure cache. When one user finishes, his copy of the stored procedure is available to the next user, and so on.

Since the access plan for a stored procedure is created from the first set of user data, the access plan may not be the best one for all users of the stored procedure. If the value of parameters passed to a stored procedure vary widely, and may benefit from a new access plan each time, you can create or execute the stored procedure using the WITH RECOMPILE option. Even though using WITH RECOMPILE can impact performance, there are still the benefits that accrue from enforcing consistent, modularized access.

Stored procedure input parameters that will be used in a WHERE clause should match the data type of the column against which they are being compared. The exception is a char(n) column, which allows NULLs. This should be represented as a varchar(n) column since SQL Server treats NULL columns as variable length. This will decrease the overhead of data conversion.

As with stored procedures, views are stored on disk in query tree format, which is the output of parsing and normalization. When executed, views and stored procedures must go through compilation to determine the optimal access plan to get to the data. However, unlike stored procedures, views are kept in the procedure cache only in query tree format, so they must be recompiled each time they are used.


Efficient Index Design

Efficient index design is based on an understanding of the SQL Server optimizer as well as the internal index storage structures and the queries that will access the data. Therefore, the following guidelines should be applied to the design of optimal indexes.

General Guidelines

Examine all queries in detail based on the query design guidelines. Base index design on the optimization characteristics of the queries. Important optimizer characteristics are as follows:

  • An UPDATE will be direct, provided that a unique index exists from which the query optimizer can determine that no more than one row qualifies for the update and that the target table is the only table in the UPDATE statement. Moreover, the columns being updated must be fixed length rather than variable length. (NULLs are internally stored as variable-length data type columns.)
  • A DELETE will be direct, provided that a unique index exists from which the query optimizer can determine that either zero or one row qualifies for the update and that the target table is the only table in the DELETE statement.
  • An INSERT will be direct, provided that the table into which the rows are being inserted cannot be a table that is being read from in the same command. In addition, if rows are being inserted into the target table, then no columns from the target table can be used in the WHERE clause of the query.
  • Indexes are more efficient when narrow. Narrow indexes result in more index rows per page and fewer index levels. Consequently, a greater number of index key values can be cached, which results in fewer I/Os.
  • The SQL Server optimizer is capable of analyzing a great number of index and join possibilities. Thus, a greater number of narrow indexes provides the optimizer with more selections than only a few wide indexes. However, do not maintain unnecessary or under-used indexes because they add to storage and maintenance overhead.
  • The SQL Server optimizer only maintains distribution statistics on the most significant columns of a compound, composite, or multicolumn index. Therefore, selectivity should be great for the first column of the index.
  • A large number of indexes on a table will affect UPDATE, INSERT, and DELETE performance, since all indexes will be appropriately adjusted. In addition, all paging operations are logged, causing further I/O.
  • Indexing a column that is frequently updated will severely degrade performance.
  • Because of storage overhead and I/O considerations, a small contrived index will result in better performance than a larger index. However, there may be a significant tradeoff with respect to maintaining the contrived column.
  • Attempt to analyze the frequency of use of each critical query because this will point to the indexes that are used the most. Accordingly, apply appropriate optimizations to these indexes first.
  • Any column in the WHERE clause of a query is a potential index column since the optimizer is primarily focused on this clause.
  • Indexing small tables (less than one extent (eight pages) in size) is not optimal because it is usually faster and cheaper to perform a table scan.
  • Design indexes that will generate the fewest number of I/Os by using page reads. An effective approach is to calculate the number of index rows per page and analyze the worst case scenario with respect to the number of reads required to obtain the solution set.

Clustered Indexes

The following guidelines apply to the design of clustered indexes:

  • Use the primary key column(s) when used for the WHERE clause of queries.
  • Examine any columns used in joins.
  • Queries that return many rows may benefit from the use of a clustered index.
  • A column that contains a lot of redundant data values (moderate number of unique values) is a candidate for a clustered index.
  • Columns accessed by range are excellent candidates for clustered indexes.
  • Clustered indexes should not be built on columns that undergo frequent change because this will result in the entire row moving. You must be especially aware of this in high-volume transaction-processing systems where data tends to be volatile.
  • Columns used in conjunction with ORDER BY or GROUP BY clauses are candidates for clustered indexes. If such an index exists on the column(s) specified in the ORDER BY, then a worktable will not be created, since the rows are already ordered. GROUP BY always results in the creation of a worktable.
  • Columns that are accessed sequentially are candidates for clustered indexes.
  • Do not use clustered indexes for "covered queries." The more columns there are in an index, the greater the chance for index column change, resulting in excessive page I/O.

Nonclustered Indexes

The following guidelines apply to the design of nonclustered indexes:

  • Nonclustered indexes are exceptional for use by queries where you get an exact match.
  • Decision support systems should take advantage of nonclustered indexes since there are few data update, insert, or delete operations. Therefore, a liberal number of nonclustered indexes can be built to aid in information retrieval. However, you may want to drop and rebuild these indexes during data refresh cycles to avoid index-manipulation overhead.
  • Covered queries are queries in which all the fields identified in the SELECT statement are represented in the nonclustered index; therefore, SQL Server can satisfy the query without accessing the data page. Adding columns to these indexes to enable a covered query can improve performance, but this approach needs to be weighed against the increased update and storage costs of maintaining extra columns in the index.


Query and Index Design Strategy Summary

Efficiency of design is the key. Such a design philosophy is based on the following:

  • Operational characteristics of the SQL Server optimizer
  • Understanding of concurrency and consistency
  • Understanding of the internal data and index storage structures

Basing query and index design on this knowledge will yield optimal performance of the queries used by applications and the system.


Query and Index Tuning

Under most circumstances, if an efficient database design has been implemented on a suitable hardware platform, the SQL Server query optimizer will efficiently optimize most queries, resulting in exceptional performance. However, if a particular query is performing poorly and performance monitoring of critical system resources indicates no bottleneck problems, query and/or index tuning may be necessary. The following sections provide recommendations for tuning slow queries and inefficient indexes.


Analyze Query Usage

Analyzing a query is a process of elimination. Before you begin to dissect the structure of the SQL query, you should eliminate other contributing factors that may influence SQL query performance. Having eliminated these other factors, it is then appropriate to analyze the structure of the query.

Views

Although SQL queries that access views can be relatively simple in structure, the actual view can be complex in structure. Consequently, you should analyze a view for poor performance before any queries that access it are analyzed. Analyze the SQL statement that creates the view using the recommendations for analysis and design presented earlier in this chapter.

Triggers

Slow query performance can be attributed to a trigger that is defined for a table associated with the query. It may be that the trigger, and not the query, is performing slowly. However, trigger overhead is usually very low. Because the time involved in running a trigger is spent mostly in referencing other tables, it is the location of the other tables that may be the cause of the slow performance. Check for physical page reads from disk.

Stored Procedures

Optimization of the search clause is based on the set of values provided when the stored procedure is first executed. The stored procedure then remains in cache (the query is not reoptimized each time it is executed). This process assumes that the first set of values used with the stored procedure is representative. If this is not the case, it is necessary to force a recompile of the stored procedure by executing WITH RECOMPILE, restarting SQL Server, or by executing the sp_recompile stored procedure.

Since stored procedures are not re-entrant, if two processes execute a stored procedure concurrently, two copies of the stored procedure are compiled, optimized, and stored in cache. The copies stored in cache remain there until they are aged out of cache or until they are forced to recompile either explicitly, by executing sp_recompile or restarting SQL Server, or implicitly, by dropping an index or table that is referenced by the stored procedure.

Note

Stored procedures are automatically recompiled when objects or indexes on any of the tables used by the access plan are dropped. They are not recompiled when you add indexes or run UPDATE STATISTICS.

Concurrency

A query may be performing slowly due to concurrency conflicts with other queries. To determine if concurrency problems do exist, observe if the query runs efficiently during some periods of the normal work cycle and slowly during others. If this behavior is exhibited, then you should check the locking levels of other active SQL Server processes.

To determine if the query being analyzed is being blocked by another process, run sp_who. You can then execute sp_lock to obtain more detail about the state of process locks with respect to the identified queries. There are also SQLServer-Locks performance monitor counters, which are useful for determining the types of locks held system wide. The most useful counters for determining if server concurrency problems exist are Total Blocking Locks, Total Demand Locks, and any locks that are exclusive. If any of these values is high with respect to the number of executing query processes, then a concurrency problem probably exists.


SQL Query Structure Analysis

After other performance-limiting factors have been considered, you should examine the structure of the SQL query and analyze if intelligent indexes are available for selection by the query optimizer. The following questions will help you fine-tune the query and available indexes.

Are there any unmatched data types?

Unmatched data types may indicate that a join clause is comparing values of different data types. A common problem is a join clause involving two character columns where one column is defined as char/not null and the other as char/null represented internally as varchar. The optimizer considers the two columns being joined as separate data types and therefore may not consider the clause an optimizable one.

Are there a lot of string operations or data conversions?

If there is a significant number of string operations or data conversions in the SQL statement, they may be more appropriate in the calling application. Extensive string manipulation and data conversions consume processor resources. On a heavily loaded SQL Server, this resource consumption may cause queries to perform slowly.

Are efficient indexes being used?

Look at the table(s) being accessed by the query being analyzed to determine if any indexes exist. You can access this information by using SQL Enterprise Manager or by executing the sp_help stored procedure. If indexes do exist, do they meet the index selection and efficient design criteria discussed in "Query and Index Design," earlier in this part? Remember, the index must be considered "useful" by the optimizer before it is selected.

Are the existing indexes useful?

Is the optimizer selecting any of the available indexes? To determine this, set the following Transact-SQL options ON:

  • SET SHOWPLAN ON—Generates a description of the query execution plan for the query.
  • SET NOEXEC ON—Compiles a query but does not execute it. This option must be turned off to execute queries.

After the query execution plan is available for viewing, check for references to Using Clustered Index or Index: index_name; the associated clustered or nonclustered index will be used for that portion of the query. If Table Scan is displayed, the query optimizer did a row-by-row sequential scan of the table due to lack of a useful index or because such a scan is cheaper in terms of I/O processing than using an index.

Why isn't the optimizer choosing an index?

If the optimizer has indexes to choose from but does not select them, check for the following causes:

  • The data in the table has changed significantly since the original indexes were created. Executing the UPDATE STATISTICS statement against the table(s) or index(es) will refresh the distribution statistics and result in a higher probability of index selection by the optimizer.
  • The available indexes were no better than a table scan with respect to the amount of I/O that would be incurred. This is because the indexes either had no relationship to the SELECT list and/or the WHERE clause, or the subsequent reading of the index plus the reading of the data is more expensive than just reading the data sequentially—the table itself is smaller than the combination of the table and the index.

Addressing these problems generally results in more efficient queries. Nonetheless, if the distribution statistics are current and it appears that an index was appropriate, further investigation of the optimizer selection process is warranted.

What is the optimizer thinking?

To obtain a detailed description of the index-selection criteria and join plan associated with a query, perform the following steps by using ISQL/w or SQL Enterprise Manager:

Execute DBCC TRACEON (-1)—Turns tracing on for all connections.

Execute DBCC TRACEON (3604)—Sends output to the screen.

Execute DBCC TRACEON (302)—Prints information about the optimizer's index selection.

Execute DBCC TRACEON (310)—Prints information about the optimizer's join selection.

Execute the query being analyzed.

Execute DBCC TRACEOFF (-1)—Turns tracing off for all connections.

The output from these steps reveals the selection criteria for indexes and joins and the number of access plans considered for the query.

What if the query is slow even with an index?

If the optimizer chooses an index but the query is still slow, the problem may be resource oriented. Use the memory-monitoring techniques discussed earlier to determine if excessive paging is occurring. If this is the case, you will need to review the size and makeup of the index. Remember, the smaller the index, the better. You may also want to change the FILLFACTOR to include more indexes on an index page. However, this can result in more frequent page splits, which decreases performance.


Tune the Query

If, after examining the query execution plan, you come to the conclusion that the optimizer has chosen the best plan, you should then consider changing the query so that the optimizer will generate a more efficient query execution plan. This can be accomplished by applying many of the techniques and strategies presented earlier in this part. Use of the following commands will also help in tuning the query. These can be executed from SQL Enterprise Manager or ISQL/w.

  • SET STATISTICS TIME ON—This option displays the time it took to parse and compile each statement, along with the time it took to execute each step in the query plan. This option can be used to compare the performance of modifications made to queries and/or indexes.
  • SET STATISTICS IO ON—This option displays the number of scans, the number of logical reads (pages accessed), and the number of physical reads (disk accesses) for each table referenced in the statement. This option also displays the number of pages written for each statement.

If the query is still running slowly after query and index tuning, contact the appropriate support personnel to determine if a more serious problem exists. As a last resort, you can force the optimizer to join the tables in the order dictated by the query by executing the SET FORCEPLAN ON statement.


Using UPDATE in SQL Server 6.5

Microsoft SQL Server can process an UPDATE statement using one of four possible methods. These methods are deferred, in-place, on-page delete/insert, and full delete/insert. This section discusses the rules that determine which method is used.

The decision concerning deferred update is made at compile time; the decision concerning the three nondeferred methods is made at execution time on a row-by-row basis. Since Showplan is based on compile-time information and not run-time information, the update mode it reports may be different from how the query was actually executed at run time. If the Showplan output indicates DEFERRED, the actual access plan used is always deferred. For nondeferred updates, you can use trace flag 323 to see exactly how the query was processed. Trace flag 323 is slightly different from other trace flags; it will only display output to the error log, not to the local session, and it will only write to the error log if SQL Server is started from the command prompt—for example:

sqlservr -c - dc:\mssql\data\master.dat


Deferred Update

When the deferred method of update is used, the changes are applied to all rows of the table by making log records in the transaction log to reflect the old and new value of the column(s) being modified (in the case of UPDATE operations) or to reflect the values that will be inserted or deleted (in the case of INSERT and DELETE, respectively).

When multiple rows can qualify for the update, if the row can increase in size or if indexed columns are updated, the rows could move out ahead of the current position and be processed again. For example:

UPDATE T1
SET col1 = col1 + 1

In this case, deferred mode must be used. If only a single row can qualify, deferred update is not required.


Update in Place

When an update is performed in-place, a log record of type MODIFY is recorded in the log. This record contains only the differences between the old and new row values, not their actual values, and it cannot handle changes in row length. For in-place updates, the following restrictions apply:

  • The table cannot contain an UPDATE trigger.
  • The table cannot be marked for replication.
  • There can only be one table involved in the UPDATE statement. Primary/foreign key references automatically mean that more than one table is involved. This rule includes any subselect in the update query including a self-join. Whenever more than one table is involved, a deferred update takes place.
  • The column being updated cannot be part of a clustered index.
  • The column being updated can be of variable length, but the new row length must be exactly the same as the old row length.
  • The new row cannot be too different from the old one. The number of differing bytes cannot be more than one half the total row size, and the total number of discontiguous differing blocks cannot be more than three. Differing blocks within 8 bytes are considered a single block.

    Consider the following code sample:

create table t1 (col1 int, col2 char(60))

go

insert t1 values

(1,'abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz')

insert t1 values

(2,'abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz')

— continue for 1000 rows —

go

create unique index idx1 on t1 (col1)

go

If you try to change more than one half of the row size—do not confuse this with one half of the column length—delete/insert is performed instead of in-place. Since this example changes 33 bytes of a 64-byte row size, delete/insert is performed.

update t1 set col2 =

'zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzhijklmnopqrstuvwxyz'

where col1 = 1

go

If you have more than three differing blocks within the column being updated, delete/insert is performed. Since this example changes 4 bytes, each in a separate block, delete/insert is performed.

update t1 set col2 =

'ZbcdefghijZlmnopqrstuvZxyzabcdefghijkZmnopqrstuvwxyz'

where col1 = 2

go

For single-row, in-place updates, the optimizer must be able to determine ahead of time that only one row will qualify. That is, there must be a unique index, and that index must be used to drive the search. The column being updated can be a nonclustered index key, and that index may also be used to drive the search.

Multiple rows can be updated in-place but only if the following conditions apply:

  • The updated column is fixed length.
  • The clustered index is not updated.
  • The updated column cannot be a nonclustered index column used to drive the search. However, other nonclustered index columns can be updated.


On-Page Delete/Insert

On-page delete/insert is an option when one of the above requirements for in-place update is not met. It is more efficient than a full delete/insert because the same row slot is used and only those nonclustered indexes that are actually updated are fixed. If the new row is not the same size as the old row but there is still enough room on that page for the new row, then on-page delete/insert is used.


Full Delete/Insert

In full delete/insert, full delete and insert log records are recorded for the row being updated. In addition, all nonclustered index keys are deleted and reinserted, regardless of whether or not they were updated. Full delete/insert is used when on-page delete/insert cannot be used: either when there is not enough room on the page for the new row, or when a clustered index key is updated.


ANSI Options in Procedures and Triggers

SQL Server 6.0 and 6.5 both added new SET options to enable ANSI behavior in Transact-SQL. Since these SET options can be issued by any client connection calling a stored procedure or firing a trigger, writers of stored procedures and triggers should not assume a standard environment will be in effect when the procedure or trigger is executed. Developers of procedures and triggers can do two things to address this issue:

  • When testing procedures or triggers, you should always ensure that they work in both ANSI-compliant and non-ANSI environments. To do this, test with the ANSI options both on and off—for example, in SQL Server 6.5 do the following:

USE mydb

go

SET ANSI_DEFAULTS OFF

go

EXEC TestProc

go

SET ANSI_DEFAULTS ON

go

EXEC TestProc

go

  • When writing procedures and triggers, developers should consider whether running in either an ANSI or non-ANSI environment may affect the operation of the Transact-SQL statements they are using. If the commands used may be affected by the setting of some ANSI option, they should include a SET statement at the start of the procedure or trigger that ensures the statements will operate correctly. When a SET statement is issued in a procedure or trigger, the option is reset to whatever setting was in effect before the procedure or trigger was executed when the procedure or trigger quits. For example:

CREATE PROCEDURE TestANSI @var1 char(8) AS

/* Allow for @var1 to be NULL and still compare correctly */

SET ANSI_NULLS OFF

SELECT MyCol

FROM MyTable

WHERE MyKey = @var1

go

When the procedure TestANSI is executed, it sets up the ANSI_NULLS option needed to let the comparison WHERE MyKey = @var1 to succeed when @var1 contains a null value. When TestANSI completes, the ANSI_NULLS option setting for the connection returns to whatever value it had before TestANSI was executed.


Hardware Planning

When planning hardware for your SQL Server installation, think about system processors, memory, disk subsystem, and the network.

This article provides information that will help you choose the best possible hardware configuration for your database environment. SQL Server configuration parameters are addressed because they influence the performance of the hardware platform. Characteristics of the Windows NT operating system are also discussed from a hardware performance point of view.

Hardware planning as it relates to SQL Server is primarily concerned with system processors, memory, disk subsystem, and the network. These four areas make up the bulk of all relevant hardware platforms on which Windows NT and SQL Server operate. This article discusses planning considerations that are generic to all platforms and useful to scaling and implementing optimal SQL Server solutions.


System Processor: CPU

In trying to determine the CPU architecture that is right for your particular needs, you are attempting to estimate the level of CPU-bound work that will be occurring on the hardware platform. As far as SQL Server is concerned, CPU-bound work can occur when a large cache is available and being optimally used or when a small cache is available and a great deal of disk I/O activity, aside from that generated by transaction log writes, is occurring. The following questions must be answered:

  • Will the system be dedicated to SQL Server?
  • How many users or processes will access the SQL Server?
  • What will the level of transaction throughput be?
  • Is the SQL Server a departmental system or an organization system?
  • Will there be a large number of concurrent users accessing the SQL Server?
  • Will there be a great deal of aggregation occurring on the SQL Server?

The answer to these questions may have already come from the requirements. If not, you should be able to make some reasonable estimates. The bottom line is: Purchase the most powerful CPU architecture you can justify. This justification should be based on your estimates, user requirements, and the logical database design.


Memory: RAM

Determining the optimal memory configuration for a SQL Server solution is crucial to achieving stellar performance. SQL Server uses memory for its procedure cache, data and index page caching, static server overhead, and configurable overhead. SQL Server can use up to 2 GB of virtual memory (the maximum configurable value). In addition, Windows NT and all of its associated services also require memory.

Windows NT provides each 32-bit application with a virtual address space of 4 GB. This address space is mapped by the Windows NT virtual memory manager (VMM) to physical memory and can be 4 GB in size depending upon the hardware platform. The SQL Server application only knows about virtual addresses; it cannot access physical memory directly. Physical memory is controlled by the VMM. In addition, Windows NT allows for the creation of virtual address space that exceeds the available physical memory. Therefore, it is possible to adversely affect the performance of SQL Server by allocating more virtual memory than there is available physical memory.

To make a suitable estimate for an optimal memory configuration, refer to the following table for SQL Server configurable and static overhead memory requirements.

Resource | Configurable | Default value | Bytes per resource | Space (MB)
User connections | Yes | 25 | 40,960 | 0.43
Open databases | Yes | 10 | 650 | 0.01
Open objects | Yes | 5,000 | 72 | 0.04
Locks | Yes | 5,000 | 28 | 0.13
Devices | No | 256 | 300 | 0.07
Static server overhead | No | N/A | 2,000,000 | 2.00
Total overhead |  |  |  | 2.68

You can use this information to calculate a more exact memory-configuration estimate with respect to actual memory usage. This is done by taking the calculated total overhead above and applying it to the following formula:

SQL Server physical memory – total overhead = SQL Server memory cache

The SQL Server memory cache is the amount of memory that is dedicated to the procedure cache and the data cache.

The procedure cache is the amount of the SQL Server memory cache that is dedicated to the caching of stored procedures, triggers, views, rules, and defaults. Consequently, if your system takes advantage of these data objects and the stored procedures are used by many users, then this value should be proportional to such requirements. These objects are stored in the procedure cache based on the frequency of their use; you want the most-used data objects to be accessed in cache versus retrieved from disk. The system default for procedure cache is 30 percent of the available memory cache.

The data or buffer cache is the amount of the SQL Server memory cache that is dedicated to the caching of data and index pages. These pages are held in the data cache based on the frequency of their use; you want the most-used data and index pages to be accessed in cache versus retrieved from disk. The system default for data cache is 70 percent of the available memory cache.

The following example for a dedicated SQL Server illustrates a more accurate estimate of SQL Server memory requirements.

Note Although the following table is a good place to start, remember that each system's needs are different. You may need more than 16 MB of physical memory on your Windows NT machine.

Resource | Estimated value | Bytes per resource | Space (MB)
User connections | 50 | 40,960 | 0.9
Open databases | 10 (default) | 650 | 0.01
Open objects | 5,000 (default) | 240 | 0.04
Locks | 15,000 | 60 | 0.42
Devices | 256 (default) | 34 | 0.07
Static server overhead | N/A | 2,000,000 | 2.0
Total overhead |  |  | 3.44

If total physical system memory equals 48 MB (Windows NT physical memory equals 16 MB and SQL Server physical memory equals 32 MB), and you subtract the previous overhead figure (3.44) from the SQL Server physical memory, you will have approximately 28 MB total memory cache to work with on the SQL Server (procedure cache: 28.56 * 0.3 = 8.568 MB and data cache: 28.56 * 0.7 = 19.992 MB).

As overhead requirements, such as user connections and locks, increase, this value decreases, which may lead to performance problems that require tuning.


Disk Subsystem

Achieving optimal disk I/O is the most important aspect of designing an optimal SQL Server solution. The disk subsystem configuration addressed here consists of at least one disk controller device and one or more hard disk units and allows for disk configuration and associated file systems. The goal is to select a combination of these components and technologies that complements the performance characteristics of the SQL Server. Therefore, disk subsystem I/O as it relates to reads, writes, and caching defines the performance characteristics that are most important to SQL Server.

Here are the disk subsystem components and features you should look for in an intelligent, fast, SCSI-2 disk controller or disk-array controller:

  • Controller memory cache
  • Bus Master card—Processor onboard results in fewer interrupts to the system CPU(s)
  • Asynchronous read and write support
  • 32-bit EISA or PCI
  • Hardware-level RAID support
  • Fast SCSI-2 drives
  • Read-ahead caching (at least a track)

The determination of how many drives of what size, configuration, and level of fault tolerance, is made by looking at the user and application performance requirements, understanding the logical database design and associated data, and understanding the interaction between system memory and disk I/O with respect to Windows NT and SQL Server.

Here are several key concepts that serve as guidelines in the selection of appropriate disk subsystem components:

Data I/O is random

Most database I/Os (reads and writes) are random with respect to data and indexes. This is true for online transaction processing and decision support systems.

Log writes are sequential

Writes to the SQL Server transaction log are sequential and occur as large bursts of page-level I/O during the checkpoint process or during update, insert, or delete operations.

Several physical disks

Optimal access to randomly accessed data and indexes is achieved by distributing the database over several physical disk units in a single-stripped volume (RAID 0 or RAID 5). This results in multiple heads accessing the data and indexes.

Separate sequential and random data

Optimal access to sequential data is achieved by isolating it from random data and index volume(s). This is achieved by using separate physical disk units that can be RAID configured (usually RAID 1, mirrored for logs). Sequential access is faster with a single head moving in one direction.

Multiple controllers

Duplexing of intelligent disk controllers (SCSI or Array) usually yields improved performance. This is especially true of systems that must sustain high transaction throughputs, systems with small data (buffer) caches, and systems with large data volumes. In addition, if the number of physical disk units exceeds a controller's capacity, another controller is needed.

Calculate number of disks

A good way to determine the number of disk units required for an optimal disk subsystem is to multiply the number of I/Os per application transaction by the total number of application transactions per second, as generated by the users or the applications. This yields the total number of user- or application-generated I/Os per second. Take this value and divide it by the average sustainable I/Os per second of the physical disk units you use. (An average range is between 30 and 50 I/Os per second, which includes system overhead and latency.) The result is a recommended number of disk units for this particular SQL Server solution.

Calculate disk size

One way to determine the size of the disk units required for an optimal disk subsystem is to divide the total space required for the database by the number of drives determined previously. This yields a value that must then be adjusted according to the RAID level employed and/or the number of controllers employed.

Separate log and data

The minimum, optimal, disk-subsystem configuration for any SQL Server solution consists of a SCSI-type controller and at least two SCSI drives. This disk configuration is necessary to isolate the SQL Server transaction log(s) on one physical disk and the database devices or file(s) on the other physical disk.

These concepts should be used as guidelines and not as absolutes. Each SQL Server environment is unique and therefore requires experimentation and tuning appropriate to its conditions and requirements.


Network

As with intelligent disk controllers, the goal is to select an intelligent network interface card (NIC) that will not rob CPU or memory resources from the SQL Server system. This network card should meet the following minimum recommendations:

  • 32-bit EISA or PCI
  • Bus Master card—Processor onboard results in fewer interrupts to the system CPU(s)
  • Onboard memory cache


Hardware Planning Strategy Summary

When building an optimal SQL Server solution, the choice of hardware should be based on:

  • User and application performance requirements.
  • Knowledge of the Windows NT operating system.
  • Knowledge of SQL Server internals and operations.
  • The logical database design.

All too often, SQL Server solutions are made to fit generically configured hardware platforms, which results in systems that perform poorly. Consideration must be given to proper hardware configuration before the physical implementation of the database. This strategy results in less tuning and augmentation of hardware components, better initial performance, and a savings of time and (potentially) money.


Cascading Deletes and Updates of Primary Keys

SQL Server restricts the data in related tables to values that preserve
data integrity.

Microsoft SQL Server provides declarative referential integrity (DRI), which allows you to define data integrity restrictions for a table and relationships between tables, both of which are automatically enforced by SQL Server at the system level.

SQL Server conforms to ANSI Entry SQL with regard to referential integrity between primary key and foreign key columns. This requires the inserting, updating, and deleting of data in related tables to be restricted to values that preserve referential integrity.

ANSI Intermediate SQL adds "referential actions," which describe what to do with dependent foreign key values when their corresponding primary key values are updated or deleted.

This section describes how these cascading deletes and updates can be implemented with SQL Server.

DRI preserves the defined relationships between tables when records are inserted, updated, or deleted. DRI is based on FOREIGN KEY, PRIMARY KEY, and UNIQUE constraint relationships, and it ensures that related key values are consistent. SQL Server uses PRIMARY KEY, FOREIGN KEY or REFERENCES, and UNIQUE constraints to enforce DRI; a foreign key can refer to a column that is declared as either a primary key or declared with a UNIQUE constraint.

The Restrict-Only level of referential integrity requires that the following four actions be detected and prevented from completing successfully:

  • Inserting a row in a referencing table where the value of a foreign key does not match a primary key value in the referenced table.
  • Updating a foreign key value in a row in a referencing table so there is no matching primary key value in the referenced table.
  • Updating a primary key value in a row in a referenced table so a foreign key in a row in the referencing table no longer has a matching primary key value.
  • Deleting a row in a referenced table so a foreign key in a row in the referencing table no longer has a matching primary key.

Cascading updates and deletes provide an alternative to merely restricting the occurrence of the two preceding actions. When a primary key is updated, as in the third case above, a cascading update causes all referencing foreign keys to be updated to the new primary key value. When a primary key is deleted, as in the last case, a cascading delete performs one of three actions:

  • Deletes the rows that referenced the deleted primary key (CASCADE).
  • Sets the referencing foreign key values to NULL (SET NULL).
  • Sets the referencing foreign key values to the column's default value (SET DEFAULT).

Cascading updates and deletes (of primary keys) can be implemented by using either triggers or stored procedures. Descriptions of each are given below. The use of stored procedures is preferred because the cascading functionality can coexist with declared foreign keys. To use triggers to supply the same functionality, foreign keys cannot be declared.

Given the definition of a primary key, changing a primary key value should be a relatively rare occurrence; deleting a primary key should be a less rare operation.


Cascading Deletes/Updates with Stored Procedures

Cascading deletes and updates can coexist with DRI FOREIGN KEY and REFERENCES constraints as long as the cascading operations are performed before the corresponding constraint checks are done. The data manipulation statements (inserts, updates, and deletes) should be managed by using stored procedures rather than by allowing users to directly manipulate table data; the statements can be executed directly, but encapsulating them in stored procedures provides additional security and maintainability. The users call the appropriate stored procedure for the required operation; permission is granted on the stored procedures and revoked from the tables to ensure proper use.

The cascading update stored procedure would first insert a new row in the primary table, duplicating all values of the existing row but including the new primary key value. It would then update the foreign keys in the dependent table(s) and then delete the original row in the primary table.

The cascading delete stored procedure would first either delete the foreign key rows or update them to either NULL or their default value. It would then delete the row in the primary table.

If further cascading was needed, the delete or update of the foreign keys would be done using another delete/update stored procedure for the dependent table.

The insert statement does not require any special processing beyond what DRI automatically provides, so the insert could be done directly or wrapped in a stored procedure for consistency.

To perform multirow updates and deletes, you can create temporary tables containing the primary keys of the rows that are to be processed and then create a cursor on the temporary table to call the procedure for each row, one by one. This is because a range of rows cannot be passed to a subsequent update or delete stored procedure to perform the cascading operation.


Cascading Deletes/Updates with Triggers

Triggers cannot be used to perform cascading updates and deletes if foreign key-to-primary key relationships, or foreign key-to-unique relationships, have been established using SQL Server's DRI. The DRI constraints are tested first; the trigger only fires if the update or delete passes all constraint restrictions. Therefore, because any update or delete that would need to be cascaded would fail the constraint checking, DRI FOREIGN KEY constraints must not exist on those relationships that need to be cascaded.

By not declaring the FOREIGN KEY (or REFERENCES) constraints, the cascading updates and deletes can be implemented using triggers. The PRIMARY KEY and UNIQUE constraints should still be used, however.

A delete trigger on the primary table either deletes the rows in the dependent table(s) or sets all corresponding foreign keys to NULL (or their default value). The cascading delete is easily performed with nested triggers, each deleting all rows in dependent tables. Cascading triggers that set null or defaults may be more problematic due to multirow considerations with triggers if the updates must be cascaded to additional levels of dependent tables. However, if the foreign keys are not part of the dependent table's primary key, they can be updated from within the trigger.

For implementing cascaded updates, an update trigger on the primary table should perform the required data modifications on the secondary table(s). Again, as long as the foreign key being updated is not part of the dependent table's primary key, it can be updated from within the trigger.

The following is an example of a cascading delete trigger on the titles table that deletes all rows in the titleauthor table with matching foreign key values. Because title_id is part of the primary key of titleauthor, this trigger assumes there are no subsequent levels of tables with foreign keys referring to titleauthor. This will work correctly even for multirow deletes.

CREATE TRIGGER DelCascadeTrig
    ON titles
    FOR DELETE
AS
    DELETE titleauthor
        FROM titleauthor, deleted
        WHERE titleauthor.title_id = deleted.title_id

The following is an example of setting a null within a delete trigger on the titles table that updates all rows in the titleauthor table with matching foreign key values. Again, because title_id is part of the primary key of titleauthor, this trigger assumes there are no subsequent levels of tables with foreign keys referring to titleauthor. This also works for multirow deletes.

CREATE TRIGGER DelSetNullTrig
    ON titles
    FOR DELETE
AS
    UPDATE titleauthor
        SET titleauthor.title_id = NULL
            FROM titleauthor, deleted
            WHERE titleauthor.title_id = deleted.title_id

The following is an example of a cascading update trigger on the titles table that updates all rows in the titleauthor table with matching foreign key values. Again, because title_id is part of the primary key of titleauthor, this trigger assumes there are no subsequent levels of tables with foreign keys referring to titleauthor.

CREATE TRIGGER UpdCascadeTrigBad
    ON titles
    FOR UPDATE
AS
    IF UPDATE(title_id)
    BEGIN
        UPDATE titleauthor
            SET titleauthor.title_id = inserted.title_id
                FROM titleauthor, deleted, inserted
                WHERE titleauthor.title_id = deleted.title_id
        END
    END

This will NOT work correctly for multirow updates because there is no way to match a given row in the deleted table with its corresponding row in the inserted table without adding a second unique identifier that never changes its value. This is the same problem that arises when cascading needs to be taken to subsequent levels and the foreign key is part of the primary key in the dependent table and the primary key in the dependent table is referred to by other foreign keys.

To prevent multirow updates, the preceding trigger should be rewritten to prevent the update from affecting more than one row of the original table (titles, in this case). The update in the trigger may well update more than one row in titleauthor; however, this solution to the multirow problem might just cause the problem to reappear at the next level of the cascade.

CREATE TRIGGER UpdCascadeTrig
    ON titles
    FOR UPDATE
AS
    IF UPDATE(title_id)
    BEGIN
      IF @@ROWCOUNT = 1
        UPDATE titleauthor
            SET titleauthor.title_id = inserted.title_id
                FROM titleauthor, deleted, inserted
                WHERE titleauthor.title_id = deleted.title_id
      ELSE
        ROLLBACK TRANSACTION
        RAISERROR ('Multirow update on table "titles" not allowed.')
      END
    END

For multiple levels of cascading triggers to function properly, the "nested triggers" sp_configure parameter must be 1. Triggers can only be nested to 16 levels.

sp_configure nested 'triggers',1


Removing Duplicate Primary Keys from a Table

SQL Server has various mechanisms for enforcing entity integrity, including indexes, UNIQUE constraints, PRIMARY KEY constraints, and triggers.

Microsoft SQL Server tables should never contain duplicate rows nor nonunique primary keys. Duplicate primary keys are a violation of entity integrity and should be disallowed in a relational system. SQL Server has various mechanisms for enforcing entity integrity, including indexes, UNIQUE constraints, PRIMARY KEY constraints, and triggers.

Despite this, under unusual circumstances, duplicate primary keys occur; when they occur, they must be eliminated. One way they can occur is if duplicate primary keys exist in nonrelational data outside SQL Server, and the data is imported while primary key uniqueness is not being enforced. Another way they can occur is through a database design error, such as not enforcing entity integrity on each table.

Duplicate primary keys are noticed when you attempt to create a unique index, which will quit if duplicate keys are found. This message is:

Msg 1505, Level 16, State 1
Create unique index aborted on duplicate key.

This section discusses how to locate and remove duplicate primary keys from a table. However, you should closely examine the process that allowed the duplicates to happen and make changes to prevent its recurrence.

For this example, start ISQL/w and create a table with duplicate primary keys values in the pubs database. In this table, the primary key is the two-column combination col1 and col2.

create table t1(col1 int, col2 int, col3 char(50))
insert into t1 values (1, 1, "data value one")
insert into t1 values (1, 1, "data value one")
insert into t1 values (1, 2, "data value two")

Note You cannot create a unique index or PRIMARY KEY constraint since two rows have duplicate primary keys.

To identify and remove the duplicates

Identify which rows have duplicate primary key values:

SELECT col1, col2, "num_dups"=count(*)

FROM t1

GROUP BY col1, col2

HAVING count(*)>1

This returns one row for each set of duplicate primary key values in the table. The last column in this result set is the number of duplicates for the particular primary key value.

col1 col2 num_dups

---- ---- -------

1 1 2

If there are only a few sets of duplicate primary key values, the best procedure is to delete these manually on an individual basis. For example:

set rowcount 1

delete from t1

where col1=1 and col2=1

The rowcount value should be n–1 where n is the number of duplicates for a given key value. In this example, there are two duplicates, so rowcount is set to 1. The col1/col2 values are taken from the above GROUP BY query result. If the GROUP BY query returns multiple rows, the SET ROWCOUNT query will have to be run once for each of these rows. Each time it is run, set rowcount to n–1 where n is the number of duplicates for the particular primary key value.

Before deleting the rows, you should verify that the entire row has been duplicated. While unlikely, it is possible that the primary key values are duplicates, yet the row as a whole is not. An example of this would be a table with Social Security Number (SSN) as the primary key that has two different people, or rows, with the same number, each having unique attributes. In such a case, whatever malfunction caused the duplicate key may have also caused valid unique data to be placed in the row. This data should be copied out and preserved for study and possible reconciliation prior to deleting the data.

If there are many distinct sets of duplicate primary key values in the table, it may be too time-consuming to remove them individually. In this case, the following procedure can be used:

To identify and remove many distinct sets of duplicates

Run the above GROUP BY query to determine how many sets of duplicate primary key values exist and the count of duplicates for each set.

Execute sp_dboption on the pubs database.

sp_dboption pubs, "select into/bulkcopy", true

Select the duplicate key values into a holding table. For example:

SELECT col1, col2, "num_dups"=count(*)

INTO holdkey

FROM t1

GROUP BY col1, col2

HAVING count(*) > 1

Select the duplicate rows into a holding table, eliminating duplicates in the process. For example:

SELECT DISTINCT t1.*

INTO holddups

FROM t1, holdkey

WHERE t1.col1 = holdkey.col1

AND t1.col2 = holdkey.col2

At this point, the holddups table should have unique primary keys; however, this will not be the case if t1 had duplicate primary keys, yet unique rows (as in the SSN example above). Verify that each key in holddups is unique and that you do not have duplicate keys, yet unique rows. If this query returns any rows, you have duplicate keys only (no unique rows).

SELECT col1, col2, "num_dups"=count(*)

FROM holddups

GROUP BY col1, col2

HAVING count(*)>1

  • If the query returns no rows, you have no duplicate keys. Continue with step 6.
  • If the query returns rows, you have duplicate keys, yet unique rows. Stop here and reconcile which of the rows you want to keep for a given duplicate key value. This will usually entail either discarding a row or creating a new unique key value for this row. Take one of these two steps for each such duplicate primary key in the holddups table.

Delete the duplicate rows from the original table. For example:

DELETE t1

FROM t1, holdkey

WHERE t1.col1 = holdkey.col1

AND t1.col2 = holdkey.col2

Put the unique rows back into the original table. For example:

INSERT t1 SELECT * FROM holddups


Part 4 - Maintaining Your SQL Server Solution

Despite your best efforts, you may encounter problems with your SQL Server solution. The articles in Part 4 can help you isolate problems and solve them quickly or even prevent them from occurring in the first place:

  • Upgrading to SQL Server 6.5
  • Managing Replication
  • Database Consistency Checker
  • Scanning the SQL Server Error Log or DBCC Output for Errors
  • Implementing Microsoft SQL Server
  • Tuning
  • SQL Executive Troubleshooting
  • Deadlocking with Distributed Transactions
  • Orphaned Connections
  • Tracing SQL Generated by the Microsoft SQL Server ODBC Driver
  • Understanding and Resolving SQL Server Blocking


Upgrading to SQL Server 6.5

Be sure you have the latest and greatest Microsoft database solution—upgrade to Microsoft SQL Server version 6.5 today!

Most of the utilities shipped with this resource guide require SQL Server version 6.5. If you are using SQL Server versions 6.0 or 4.2x, you'll need to upgrade to use the utilities.

This article describes some upgrade issues you should be aware of and offers backup and configuration strategies that can be performed before upgrading to SQL Server 6.5. Be sure to review the Microsoft SQL Server documentation about upgrading SQL Server before performing any SQL Server upgrade. The following topics will be discussed:

  • Back Up
  • Configuration
  • Troubleshooting


Back Up

Before beginning an upgrade, it is strongly recommended that you have a valid backup. Since Windows NT provides a file backup facility and SQL Server provides dump and load capabilities, it is best to perform two types of backup: a Microsoft Windows NT backup and a Microsoft SQL Server dump.

For information about backing up, see the Windows NT documentation and the documentation included with Microsoft SQL Server.


Microsoft Windows NT Backup

To verify the names of the files to back up

Make sure SQL Server is running.

Go to a query window.

Set your database to master.

Execute:

select * from sysdevices where cntrltype = 0 or cntrltype = 2

Note the values in the phyname column.

To perform a backup using Windows NT

Stop SQL Server.

On the Start menu, point to Programs and then Administrative Tools (Common). Click Backup.

Back up all the data and log device files, including Master.dat. By default, the files you'll need to back up end in the extension .dat.

Copy all the data and log device files to tape or to a temporary directory other than their original locations and other than \Sql, \Sql60 or any of their subdirectories. This prevents accidental deletion of the SQL directory.

Note This step assumes that you are backing up your data and log device files before upgrading to SQL Server version 6.5. If you choose to back up your SQL Server version 6.5 database, do not copy data and log device files to \Mssql.

It is a good idea to have a recent backup of the Registry. Refer to the section "Backing Up Disk Files to Tape" in the Windows NT documentation to learn how to back up the local Registry to tape. After the upgrade successfully completes, you can delete the temporary directory.


Microsoft SQL Server Dump

The following sections provide steps for using Microsoft SQL Server to dump your database to a backup device.

Store Result Sets

It is useful to keep the result sets of SELECT statements against the sysdatabases, sysdevices, and sysusages tables in the master database.

Note In some cases, it is also useful to store information from syslogins, sysremotelogins, sysservers, and sysconfigures.

To store these result sets

Make sure SQL Server is running.

In SQL Enterprise Manager, make a note of the available backup devices.

If you are unsure of how to do this, see "Backing Up and Restoring" in SQL Server Books Online.

Go to a query window.

Execute the following:

use master

go

print 'select * from sysdatabases'

select * from sysdatabases

print 'select * from sysdevices'

select * from sysdevices

print 'select * from sysusages'

select * from sysusages

Note If you've chosen to store other information, enter these additional lines:

print 'select * from syslogins'

select * from syslogins

print 'select * from sysremotelogins'

select * from sysremotelogins

print 'select * from sysservers'

select * from sysservers

print 'select * from sysconfigures'

select * from sysconfigures

Save the result sets to a directory other than \Sql, \Sql60, or any of their subdirectories.

Note This step assumes that you are dumping your result sets before upgrading to SQL Server version 6.5. If you choose to dump your SQL Server version 6.5 database, do not save the result sets to the \Mssql directory.

Stop SQL Server.

Use Sqldump.sql Script

The next step to backing up your SQL Server database is to execute a series of consistency checks and a stored procedure on each database on your SQL Server.

Go to a Windows NT command prompt and change your directory to the \Sql\Binn or \Sql60\Binn directory.

Note If you are dumping your SQL Server version 6.5 database, change your directory to the \Mssql\Binn directory.

Execute the following:

sqlservr -c -m

Then, minimize the command-prompt window.

Note -c starts SQL Server independent of the Windows NT Service Control Manager; -m starts SQL Server in single-user mode.

Copy the Sqldump.sql script from the BackOffice Resource Kit CD-ROM to the \Sql\Binn or \Sql60\Binn directory.

Note If you are dumping your SQL Server version 6.5 database, copy Sqldump.sql to the \Mssql\Binn directory.

Open another Windows NT command-prompt window, change to the \Sql\Binn or \Sql60\Binn directory, and execute:

isql -Usa -P password -S server_name -n -iSqldump.sql oOutput.sql

The Sqldump.sql script creates a template that runs on each database.

Note If you are dumping your SQL Server version 6.5 database, change to the \Mssql\Binn directory before executing the above script.

Use the output file created in step 4 as the input file and create a new output file for the result set of the next query as follows:

isql -Usa -P password -S server_name -n -iOutput.sql -oNewoutput.sql

This step runs sp_helpdb, DBCC CHECKDB, and DBCC NEWALLOC on each database, then saves the output to a new file.

Dump Databases

To dump your databases to the backup device

Check Newoutput.sql for any errors. Consult your system administrator if there are any errors.

If the databases are clean, proceed to dumping each database as follows:

isql -Usa -P password -S server_name -Q"dump database database_name to dump_device_name"

where dump_device_name is one of the backup devices you noted during the "Store Result Sets" section earlier in this part.

After this completes, take SQL Server out of single-user mode as follows:

  • Close both command-prompt windows.
  • Start SQL Server as a service using either the SQL Service Manager, SQL Enterprise Manager, or the MSSQLSERVER service in Control Panel.


Configuration

The following sections describe how to configure SQL Server 6.5.


Prepare SQL Server 6.0

To prepare your SQL Server 6.0 to be upgraded to version 6.5

From a query window, set the default database of the system administrator (SA) to master by executing:

sp_defaultdb sa, master

Make sure all the databases are not set to read-only by reviewing the sp_helpdb output from the Sqldump.sql script (see the status column).

Check the SQL Server documentation to determine how much physical disk space is required for the upgrade.

Run Chkupg65.exe to check that database status is acceptable, that all necessary comments exist in the syscomments system table, and that there are no keyword conflicts.

Note Chkupg65.exe is included with SQL Server 6.5.

Resolve any keyword conflicts before upgrading SQL Server.

Check how much memory is given to SQL Server.

In SQL Server version 4.21a, the minimum value is 3,072 (6 MB), while in SQL Server versions 6.0 and 6.5, the minimum value is 4,096 (8 MB). If you have additional physical RAM, increase the memory given to SQL Server to the level recommended in the SQL Server documentation.

Note Upgrading a database requires all objects to be scanned. In doing so, the upgrade may exceed some of your current run-time configuration values. To avoid this, you may want to temporarily double the size of open objects and locks before the upgrade. Make sure you have enough memory dedicated to SQL Server to accommodate the changed values.

Make sure the open databases configuration option is equal to or greater than the total number of databases on your system. You can change this configuration from a query window by using:

sp_configure [config_name [, config_value]]

Dynamic options take effect immediately after the RECONFIGURE statement has been executed. For all non-dynamic options, SQL Server must be stopped and restarted before the options can take effect. For details, see the RECONFIGURE statement.

Execute sp_helpsort to determine what sort order and character sets you have installed.

For SQL Server 6.0 and SQL Server 6.5, these values can be found in Appendix A of Microsoft SQL Server Setup (see the "About Character Sets" and "Sort Order Ids" sections). For SQL Server 4.21a, these values can be found in the configuration guide.

Shut down SQL Server and close any SQL Server windows before upgrading.


Upgrade to SQL Server 6.5

To upgrade your SQL Server 6.0 to SQL Server 6.5

Make sure you are logged on to Windows NT as administrator or someone with administrative privileges.

Check the network capabilities.

If the server being upgraded has network capabilities, continue with step 3.

If the server being upgraded does not have network capabilities, you can do one of two things:

  • Stop the workstation service to force the upgrade to use local named pipes.

    To do this, perform the following steps:

    In Control Panel, double-click Services.

    Click the Workstation service.

    Click Close.

  • Leave the Workstation service running and install the MS Loopback Adapter.

    To do this, perform the following steps:

    In Control Panel, double-click Network.

    Click Adapters, then click Add.

    Double-click MS Loopback Adapter.

Regardless of your choice, you will need to restart Windows NT once the installation completes.

Run SQL Server 6.5 Setup.exe to upgrade SQL Server.

Specify the same drive and directory for all SQL Server files to be copied during the upgrade.


Troubleshooting

This section explains some ways to correct problems you may have encountered when upgrading SQL Server.

If you encounter a problem after copying all the files, remove all SQL directories and files and remove any entries in the Registry for SQL Server. Be careful when editing anything in the Registry. Should you inadvertently delete a key that does not belong to SQL Server, you can restore the Registry with the backup you made earlier. For information about restoring the Registry, see the documentation included with Microsoft SQL Server.

Caution Using the Registry Editor incorrectly can cause serious problems that require you to reinstall SQL Server. Microsoft cannot guarantee that problems resulting from the incorrect use of Registry Editor can be solved. Use Registry Editor at your own risk.

  • If you are upgrading from SQL Server 4.2x, remove \SQLServer and \SQLMonitor from the following:

\HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\SQLServer

\HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\SQLServer

\HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\SQLMonitor

  • If you are upgrading from SQL Server 6.0, remove \MSSQLServer and \SQL Executive from the following:

\HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\MSSQLServer

\HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\MSSQLServer

\HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\SQL Executive

After the preceding entries are removed, you have two options to try the upgrade again:

  • Option One

    Reinstall the original SQL Server version.

    Once installed, stop the SQL Server services and replace all of the data and log device files, including Master.dat, with the backed-up versions. The directories for these files are listed in the phyname column of the output from the sysdevices table. You noted the file names in the "Microsoft Windows NT Backup" section earlier.

    Fix whatever caused the upgrade to fail and try the upgrade again. If the upgrade does not successfully complete, contact your primary support provider.

  • Option Two

    Reinstall the SQL Server version that you are trying to upgrade to.

    Re-execute the CREATE DATABASE statement and the ALTER DATABASE statement to re-establish the fragments.

    • The user databases need to be re-created in exactly the same way that they were originally created. That is, the device usage, log space allocation, and segment definitions in the new database must have values identical to those that existed when the database was dumped. This information is kept in the sysusages table of the master database. You can also find this information in the output from the Sqldump.sql script that you ran in the "Microsoft SQL Server Dump" section earlier.

      Load the earlier version of the SQL Server databases, while keeping the following in mind:

    • The user database dump must be a full database dump, not a transaction log dump.
    • The SQL Server version that you are trying to upgrade to must use the same sort order as the earlier version.

Note The master database is not allowed to be loaded or upgraded from earlier versions of SQL Server dumps.


Managing Replication

Microsoft SQL Server version 6.5 is everything you need in an RDBMS for distributing the most current information anywhere, anytime.

This article provides a reference for some of the most common issues you can encounter when installing and using Microsoft SQL Server replication. As with any of the information included in this guide, you should still thoroughly read and understand those chapters pertaining to replication in the documentation provided with Microsoft SQL Server.


Replication Issues

The following represents a list of some of the more common issues you can encounter when installing and using the replication feature of SQL Server.

A table does not appear in the list of possible articles when creating a publication in SQL Enterprise Manager.

Any table that will be published must have a PRIMARY KEY constraint defined using the CREATE TABLE or ALTER TABLE statement. A constraint can also be created using SQL Enterprise Manager.

Creating a unique index will not allow the table to appear in the list of possible articles. Users who have upgraded their database from prior versions of SQL Server usually do not have PRIMARY KEY constraints, but rather have used unique indexes because constraints were not supported until SQL Server version 6.0. Use ALTER TABLE to add constraints as appropriate.

LogReader and Distribution tasks do not show any entries in the Task History of SQL Enterprise Manager after setting up replication.

By default, LogReader and Distribution subsystem tasks are created with an "Auto Start" frequency. When setting up subscription servers, you can change the default for the Distribution task to a different frequency. This means the tasks will start when they are first created as tasks or any time SQL Executive is started. They run continuously in a polling "loop," pausing for each loop n milliseconds as defined by the "polling interval" set with the -i parameter. The tasks are set up with a default of one second for LogReader and two seconds for Distribution. Under this type of task scheduling, these two tasks will not display any task history, provided there are no errors, because the tasks never quit. Any error or retry attempt will cause an entry to be displayed in the Task History. If SQL Executive is shut down, these tasks will have an entry in the Task History with a message of:

This task was shutdown.

This message indicates the task ended as part of the shutdown to SQL Executive.

If a LogReader or Distribution task is scheduled to run "On Demand" or "Recurring," then it will process jobs until no more jobs are available, display information about its processing to the Task History, and then quit. For example, a LogReader task will display the following message:

Processed <n> replicated transactions consisting of <m> commands from '<published db>.'

One method that can be used to examine a more detailed view of the processing of a LogReader, Sync, or Distribution task is to add the -o parameter to each of these tasks.

-ofile_name

Do not use a space between -o and file_name or the file will not be created.

This parameter will force the task to dump details of replication processing. The parameter can be added by editing any of the tasks using SQL Enterprise Manager. Remember that if the task is set to "Auto Start," the parameter change will not take effect until SQL Executive is restarted. This parameter should only be used for troubleshooting situations as the amount of output written to the file can be substantial and could cause a degradation in performance. The -o parameter is valid for any LogReader, Distribution, and Sync task. These tasks open the file to "append" entries if the file exists and to share it so a user can view the file while the task is still executing. Remember that this parameter is only for troubleshooting purposes and only typically used when working with a support engineer. The task will not display any errors if the file cannot be created for any reason—for example, if the syntax is incorrect or the path does not exist.


Installing Replication

After SQL Server is installed, installing replication using SQL Enterprise Manager requires three steps: installing the distribution server, configuring publication servers, and configuring subscription servers.

The following procedure assumes a local distribution server when installing replication from SQL Enterprise Manager.

To install the distribution server

Click on a server.

On the Server menu, point to Replication Configuration, and then click Install Publishing.

To configure a publication server

Click on a server.

On the Server menu, point to Replication Configuration, and then click Publishing.

To configure a subscription server

Click on a server.

On the Server menu, point to Replication Configuration, and then click Subscribing.

Alternatively, on the Server menu you can point to Replication, and then click Topology to configure both publication and subscription servers. If you choose to use the Topology method, be sure to configure the publication server first. Otherwise, you will receive error 18483 because SA is not yet defined as a remote login at the site:

Error 18483: Unable to connect to site '<publication server>'


Connectivity Problems

The following are connectivity problems that may occur with replication tasks.

Distribution Task Connectivity

SQL Server replication relies on integrated security connections. A distribution task will force a trusted connection using ODBC to the subscription server. Because of this design, the distribution server must use the named pipes or a multiprotocol network library as the default network library. The Client Configuration Utility is used to set the default network library.

It is also important to understand the security context of the SQL Executive service. All replication tasks connect under the security context of the SQL Executive service. Because a trusted connection is used to connect to the subscription server, the account used by SQL Executive to log on as a service must have permissions on the subscription server. A trusted connection by a distribution task, therefore, requires that the distribution and subscription servers belong to the same domain or trusted domains. For this reason, the SQL Executive service is normally configured to log on as a domain administrator.

One simple method of testing the connectivity of replication is as follows:

Log on to the distribution server using the same account SQL Executive logs on with.

Use ISQL/w with the -E option to force a trusted connection to the subscription server.

While this test uses DB-Library and the Distribution task uses ODBC, it will still provide a reliable method of testing a trusted connection to the subscription server. Setting the subscription server to integrated security and using the odbcping utility can accomplish the same test. If a Distribution task fails to connect to the subscription or distribution server, it will display a standard ODBC error for connection failed, such as:

08001 <Microsoft><ODBC SQL Server Driver> Unable to connect to DataSource

Or

08001 <Microsoft><ODBC SQL Server Driver><DBNMPNTW> Specified SQL Server not found

LogReader and Synctask Connectivity

Both LogReader and Sync tasks connect to the publication and distribution servers using DB-Library, forcing a trusted connection. Because the default network library needs to be named pipes or multiprotocol for the subscription server, these tasks will use these network libraries to connect to their servers. Similar techniques to test Distribution task connectivity can be applied to a LogReader or Sync task. If the LogReader or Sync task fails to connect to either server, it will display the following error in the Task History of SQL Enterprise Manager:

Unable to connect to '<server>.'

If any of these tasks fail to connect to a server, they are automatically configured to retry the connection based on the configuration of the task from SQL Enterprise Manager. By default, each task is configured to retry once per minute for a maximum of 1,440 times—once each minute for 24 hours. This can be changed by clicking Options when editing the task.

Synchronized Tables

To properly understand why a table may not be automatically synchronized after subscribing, you need to understand what each type of task does for replication.

  • A LogReader task reads changes from the published database transaction log and inserts jobs into the distribution database. A LogReader task is created with a name that combines the publication server name and the published database name (for example, mypub_pubs).
  • A Distribution task reads jobs from the distribution database and executes commands from these jobs against a subscription server. A Distribution task is created with a name that combines the publisher server/published database name and subscription server/subscribed database name (for example, mypub_pubs_mysub_pubs).
  • A Sync task creates a data file (BCP format) and inserts "sync" jobs into the distribution database. The Sync task performs this operation for any new subscription or any scheduled table refresh publication.

The Distribution task synchronizes the table and its data to a subscription server. However, the Distribution task cannot perform this task until the Sync task creates a job in the Distribution database for the synchronization. Remember that a Sync task is created by SQL Enterprise Manager as part of creating a publication. If you build publications manually, you must create a Sync task using the sp_addtask procedure. SQL Enterprise Manager constructs a Sync task name by combining the publication server name, published database name, publication name, and a unique number. An example task name is mypub_pubs_authors_10.

By default, the Sync task is scheduled to run every five minutes. Because the subscription may have taken place immediately after the publication was created, the Sync task may not have executed yet. If you have created a publication and subscribed to it, check the status of the Sync task in SQL Enterprise Manager. If the Sync task has successfully completed and added the proper sync jobs, it will show an entry in the Task History like:

Sync event for publication: <publication name>. Created bcp file <filename.tmp> for article <article name> sync job.

If no new subscriptions for this publication were found you will see an entry in the Task History like:

No new subscriptions were found for articles in publication: <publication name>.

The Sync task runs even if no one has subscribed. For this reason, most users will probably want to change the default schedule of the Sync task to an interval longer than five minutes. This depends on how often new subscriptions occur or if you decide to create "scheduled table refresh" publications.


Replication Questions

The following are questions commonly asked by SQL Server customers when installing and using the replication feature.

What are all the tasks in replication and how many can I expect to have on a distribution server?

A LogReader task exists for each published database on each publication server. This task is created when the database is marked as "published." Either the stored procedure sp_dboption or SQL Enterprise Manager can be used to mark a database as "published."

A Sync task exists for every publication created. This task is created by default when a publication is created using SQL Enterprise Manager. The task must be manually added if the publication is created outside SQL Enterprise Manager. One Sync task is used no matter how many articles exist in a given publication.

A Cleanup task is created for every publication server/subscription server combination. This task is created when a subscription server is enabled on the publication server. This task is created by the sp_addsubscriber stored procedure.

A Distribution task is created for every published database/subscribed database combination. This task is created when the first publication in a published database is subscribed to by a given subscription server. This task is created by either the sp_addsubscription or sp_subscribe stored procedure.

Remember that all tasks run on the distribution server, even if the distribution server and published database(s) are on different computers.

The example below explains how many distribution tasks can be created.

Assume that a distribution server is configured to handle five publication servers, each with one published database. Three subscription servers are configured to subscribe to at least one publication for each published database for each publication server. All publications are placed in the same database on each subscription server.

Based on this description, 15 distribution tasks will be required on the distribution server to handle this environment. If a given publication was subscribed to more than one time into a different database on the subscription server, this will increase the number of tasks required by the number of databases. In the example above, if each subscription server pulls each publication into five different databases, the number of tasks increases to 75.

The following table summarizes the expected number of tasks.

Task type | Number of tasks
LogReader | 1 per published database
Sync | 1 per publication
Distribution | 1 per published database/subscribed database combination
Cleanup (sp_replcleanup) | 1 per publication server/subscription server combination

What is the difference between a "filter stored procedure" and a "custom stored procedure"?

A filter stored procedure, created to support horizontal partitioning, allows changes to be filtered before they are stored in the distribution database. A filter stored procedure can be generated by SQL Enterprise Manager or created manually by using the CREATE PROCEDURE FOR REPLICATION Transact-SQL statement. A filter stored procedure is executed in the context of the LogReader task and is applied against the changes read from the published database transaction log before jobs are placed in the distribution database.

A custom stored procedure is a hook provided for advanced replication situations. This is a procedure created by an application developer to replace a standard INSERT, UPDATE, or DELETE statement that will be executed against the subscription server. A procedure of this type should be used if you need to perform any special processing on the subscription server instead of the standard INSERT, UPDATE, or DELETE statement.

The custom procedure is specified when defining an article and must be created on the subscription server. When a job is placed in the distribution database for an article with a custom stored procedure, the procedure name will be placed in the MSjob_commands table as the command to run for the job in the distribution database. The distribution task will then execute the procedure on the subscription server.

Here is an example that uses the INSERT statement to create a custom stored procedure for the employee table in the pubs database. More code could be added to this example to customize it for your needs.

create procedure myinsert @emp_id char(9), @fname varchar(20),

@minit char(1), @lname varchar(30), @job_id smallint,

@job_lvl tinyint, @pub_id char(4), @hire_date datetime

as

insert into employee values (@emp_id, @fname, @minit, @lname, @job_id, @job_lvl, @pub_id, @hire_date)

Does SQL Server support multiple publication servers of the same table?

One of the most common questions is how many servers can modify and publish the same table. While SQL Server replication is a strategic component of Microsoft's distributed computing platform, it is not designed to be a fully distributed database management system.

SQL Server replication is not designed to handle collisions between two publishing servers. If one server updates a row that another server is trying to delete and the changes are replicated to each other, a collision can result. One possible result of the collision is that the distribution task of the server trying to replicate the update command will fail because the row it is trying to update no longer exists on the subscription server. Even worse, infinite loops of changes could result if publications are not properly defined.

Replication can support multiple publishers of the same table provided that each publisher owns a unique or discrete set of rows within the table. Each publisher would provide a method, such as a stored procedure, to prevent any modifications or inserts of rows outside the set it owns. This can easily be accomplished by including in the table a column that designates ownership and then using an horizontally partitioned article to publish that table.

What is the best way to monitor replication of changes to subscription servers?

There is no one "best" method to monitor proper replication of changes to a subscription server. Devising your own method to fit your environment is the recommended approach. Provided that the LogReader, Sync, and Distribution tasks are not encountering any errors, all changes should be replicated properly. If you suspect a particular transaction was not executed on a subscription server, it might be helpful to examine rows in the MSjob_commands table of the distribution database. This table contains all SQL statements that will be executed against subscription servers. The syntax of these commands may appear to be unusual under certain circumstances because all commands adhere to the ODBC SQL Grammar specifications.

Another table that is useful for monitoring replication is the MSlast_job_info table that is created on the subscription server database. This table will contain the last successful job that was applied to a subscription server for a given publication server. It can be compared with the MSjobs, MSjob_commands, and MSsubscriber_jobs tables to determine what jobs have and have not been applied to the subscription server.

Can Windows NT Server names conflict with replication?

If the characters in the name of your Windows NT server conflict with the valid list of characters that SQL Server supports for an identifier, you will run into problems when setting up replication. The SQL Server program issues a warning when installing the product if the Windows NT server name will cause problems when setting up replication.

The most common cause of this problem is a hyphen [-] or space character in the Windows NT computer name as defined in the Networks application in Control Panel.

What are "job batch size" and "commit batch size"?

Job batch size is parameter -b that can be configured for both a LogReader and Distribution task to control the maximum number of jobs processed by both tasks. For a LogReader task, this is the maximum number of jobs, or transactions, that will be read out of the transaction log and placed into the distribution database. This parameter is actually called transbatchsize. The default is 100 and is passed as a parameter to sp_replcmds to extract, at most, this number of committed transactions from the published database transaction log. The commit batch size -c is by default the same as the job batch size for the LogReader unless explicitly specified. It defines the maximum number of jobs that are applied to the distribution database before a COMMIT TRAN statement is executed. Decreasing this value from its default may help reduce deadlock contention between LogReader and Distribution tasks, but this could also affect the performance of a LogReader task.

The job batch size for the distribution task defines the maximum number of jobs that will be read from the distribution database to execute on a subscription server. The commit batch size defines the maximum number of jobs that will be executed on a subscription server before a COMMIT TRAN statement is executed on the subscription server.

An example may help clarify these terms. If the LogReader were configured with a job batch size of ten, it would read at most ten jobs, or transactions, at a time from the published database transaction log, and add these to the distribution database. If the commit batch size is not explicitly specified, all ten jobs would be added to the distribution database in one logical transaction—the BEGIN/COMMIT block. However, if the commit batch size were reduced to five, then five jobs at a time would be committed in one logical transaction against the distribution database. This same concept applies to the Distribution task against the subscription server. If the subscription server republishes the changes from the Distribution server, what was originally ten transactions from the publication server may now appear to be one transaction because the Distribution task committed the ten jobs as one logical transaction. Large commit batch sizes from the Distribution task can result in very large transactions to process for subscription servers that republish.

Be careful when reducing these parameters to extremely low numbers if the volume of replicated transactions is high. This may help to reduce deadlock situations, but it could decrease performance. Only proper testing for your environment will indicate what the optimal setting should be. For most users, the defaults provide a good base to work from.


Database Consistency Checker

The DBCC utilities ensure database integrity.

The database consistency checker (DBCC) utilities are a collection of programs used to verify integrity of a SQL Server database. They are conceptually similar to file system checking programs such as chkdsk in MS-DOS, Windows 95, and Windows NT, and fsck in UNIX. Like file system checking programs, DBCC can take a significant amount of time to run on large data sets. This article discusses ways to improve DBCC performance.


Overview of DBCC

Most file systems and database systems provide integrity checking utilities to periodically verify data structure consistency. For example, the Rdb Management Utility (RMU) performs functions similar to DBCC on the Oracle Rdb relational database.

Integrity checking utilities generally have a long running time when used on large data sets, and DBCC is no different. However, there are several actions that can maximize the performance and minimize the impact of DBCC.

First, a review of the DBCC statements most commonly used for integrity checking: NEWALLOC, CHECKTABLE, and CHECKDB. CHECKDB performs the same checks as CHECKTABLE but for each table in the database in succession.

  • NEWALLOC checks the integrity of all table and index page chains and checks that each page is correctly allocated. It checks the integrity of all extent chains in the database and verifies that each chain is correctly linked. NEWALLOC also checks for object ID consistency between the page, the extent, and system indexes. In general, NEWALLOC checks things at a page and inter-page level.
  • CHECKTABLE and CHECKDB, by contrast, check things at an intra-page level. In addition to checking the page chain, they check that indexes are in properly sorted order, that the data information inside each page is reasonable, that page offsets are reasonable, that the system index entries for the table are correct, and that the data row count equals the leaf row count for nonclustered indexes.

DBCC NEWALLOC and CHECKDB perform largely complementary checks and should generally both be run to get a comprehensive check of the database.

By necessity, DBCC is I/O-intensive. For NEWALLOC, running time will be roughly proportional to the database space in use. This is because NEWALLOC spends most of its time doing sequential reads. Time for this will scale linearly with the size of the database. For this same reason, NEWALLOC can be significantly faster on version 6.x because the parallel read-ahead facility increases the scanning rate.

Running time for CHECKDB is more dependent on the number of indexes in the database and number of rows per table, so the time cannot be predicted by the database size alone. Version 6.x uses parallel threads for CHECKTABLE, one to check each index. When combined with the 6.5 read-ahead facility and computers with sufficient memory, CHECKTABLE and CHECKDB can be significantly faster on 6.5 than on 6.0 or 4.2. The amount of memory needed to ensure this would be approximately the amount required to make the SQL page cache (visible with DBCC MEMUSAGE) larger than the largest individual table in the database. On computers with less memory than this, you may want to experiment with disabling read ahead for the CHECKTABLE or CHECKDB session by using trace flag 653. Setting the sp_configure RA worker threads parameter to 0 disables both read ahead and parallel CHECKTABLE. For information about how to use trace flags, see SQL Server 6.5 Books Online.

Tests indicate that SQL Server 6.5 can run DBCC NEWALLOC on a 2 GB database in less than 30 minutes when running on a typical industry-standard, symmetric multiprocessor (SMP) platform.

As for concurrency impact of DBCC, NEWALLOC and CHECKDB are both online checks in that the database can be in use while they run. There is a concurrency impact, but in many cases this is acceptable. NEWALLOC impact is primarily the I/O and CPU load from the check. In addition to the I/O and CPU load, CHECKDB places a shared table lock on each table while it's being checked. While allowing SELECTs, this will prevent modification of the table until CHECKDB moves on to the next table in the database. The share lock is necessary to achieve a reliable check.

It is usually best to run NEWALLOC when update activity in the database is at a minimum, since there is a possibility of spurious errors caused by in-progress changes during the check.


Increasing DBCC Performance

  • Use hardware with plenty of I/O capacity, since DBCC is I/O-intensive.

    One good way to increase I/O capacity is to place the database on a large RAID disk array, using as many physical drives as possible.

  • Use hardware with plenty of RAM.

    The ideal case would be sufficient RAM to enable the largest table to be contained in the SQL Server page cache. This is especially important on version 6.5 because the SQL Server page cache allows full use of parallel index checking and read ahead.

  • Ideally, you should run DBCC NEWALLOC, CHECKDB, CHECKCATALOG, and TEXTALL (if you have text/image data) in conjunction with your database dumps.

    This verifies the state of the database at the time of the dump. However, if time does not permit all of these checks, the best single check to run is NEWALLOC. It is typically faster than CHECKDB and provides a good overall check of the database. It is better to run NEWALLOC alone than to run no checks at all.

  • If your database has a nightly interval where update activity is low, rather than setting the database to single-user mode for NEWALLOC, just run it and watch for any errors.

    On the optimistic principle that most of the time the low activity will not cause spurious errors, you would only then need to schedule NEWALLOC in single-user mode when you see errors.

  • Although it is best to run both NEWALLOC and CHECKDB together, there are cases (for example, if the database is extremely large) when you would run them separately. For these cases, consider running NEWALLOC as the more frequent check, owing to the nonblocking nature and quicker running time it provides. On a less-frequent basis, supplement this with CHECKDB.
  • Run CHECKDB with the NOINDEX option.

    The most time-consuming aspect of CHECKDB is checking nonclustered indexes. These checks can be bypassed with the following syntax:

DBCC CHECKDB(MYDB, NOINDEX)

  • Run DBCC on a hot backup server.

    Sites with continuous uptime requirements often have a hot backup server on which transaction logs are loaded frequently. Otherwise, a failure on the main server would preclude continuous availability. If you have a hot backup server, it's possible to run DBCC on that server without impacting the main server. A DBCC run on the backup computer is just as valid and effective a test as a DBCC run on the main server.

    If you do not have a hot backup server, the combined benefits of the safety net it provides plus the DBCC solution can be strong arguments for getting one.


How to Run CHECKTABLE While in Production

Sometimes you may need to check a specific table or its indexes. On computers with a lot of memory, there is a technique that can sometimes allow this with very little concurrency impact, even while the computer is at modest production activity levels. It basically consists of preloading the page cache with the table and index contents using a nonblocking SELECT statement with the NOLOCK optimizer hint then checking a single index at a time to minimize the time the table is share locked. In some cases, it's possible to check a 200 MB table in less than 60 seconds using this technique. Here's how:

Verify that the activity level on the computer is modest.

This will help ensure that preloaded cache pages are not stolen by concurrent requests while DBCC runs. Here is a good query to help check this. Execute it several times and observe what queries are active.

SELECT SPID, STATUS, HOSTNAME, PROGRAM_NAME, CMD, BLOCKED

FROM MASTER..SYSPROCESSES

WHERE STATUS <> 'SLEEPING'

Verify that the table and indexes you want to check will fit into available page cache by comparing the table and index size to the page cache size.

Table and index size in 2K pages can be seen by issuing this query, where tab1 represents your table name:

SELECT NAME, INDID, DPAGES

FROM SYSINDEXES

WHERE ID=OBJECT_ID("TAB1")

Execute DBCC MEMUSAGE and inspect the size of the returned page cache value.

Only if the sum of your table and index size is less than the page cache size is it possible to use this technique. Ideally, page cache should be significantly larger to allow servicing of other requests during execution of DBCC without depleting the cache holding the table being checked.

Preload the page cache by issuing SELECTs that return no results; use NOLOCK and INDEX optimizer hints to ensure a nonblocking SELECT and that each index is covered.

This could take several minutes, depending on table size and computer I/O bandwidth.

select * from tab1 (nolock index=0) where key_id < 0

select * from tab1 (nolock index=1) where key_id < 0

select * from tab1 (nolock index=2) where key_id < 0

While the above query runs, use Performance Monitor to watch I/O versus CPU activity.

Watch all instances of the % Disk Time counter of the LogicalDisk object. Also watch the % Total Processor Time counter of the System object. To see valid disk performance information, you must have previously turned on the Windows NT diskperf setting by issuing diskperf -Y from a command prompt. For more details, see the Windows NT documentation. After all the data is preloaded, you can usually rescan the entire table with one of the above statements within a few seconds, during which CPU should be high and I/O almost 0. Do this to verify the data is still in cache.

Run DBCC CHECKTABLE on a single index of the table at a time.

During this interval, a share lock will block attempts to update the table, but (depending on the computer speed and table size) CHECKTABLE will finish checking a single index within 30 seconds to 2 minutes. For example:

DBCC CHECKTABLE(TAB1, 2)

Check the other indexes on the table.

While CHECKTABLE is running, watch closely for any blocking you may be causing. If you miscalculate and CHECKTABLE causes more blocking than you anticipate, you can usually abort CHECKTABLE by using the Transact-SQL KILL statement. Here is a good query to watch the amount of blocking:

SELECT SPID, STATUS, HOSTNAME, PROGRAM_NAME, CMD, BLOCKED

FROM MASTER..SYSPROCESSES

WHERE BLOCKED > 0

Integrity checking programs for file systems or databases tend to have long running times when applied to large data sets. Performance of SQL Server 6.5 DBCC has been significantly improved by using read ahead and parallel index checking. When SQL Server 6.5 is run on an adequately equipped platform, and the techniques mentioned in this chapter are used, it is usually possible to minimize the impact of DBCC. Specific techniques include running only the necessary DBCC utilities, understanding the concurrency impact of each utility (when, during the day, that each utility can be run), running DBCC on a hot backup server, and preloading the page cache prior to checking a specific table.


Scanning the SQL Server Error Log or DBCC Output for Errors

Windows NT ships with a powerful pattern-searching utility called findstr, which can be used to automate checking both DBCC output and SQL Server error logs.

It is necessary to frequently examine DBCC output and the SQL error logs to check for problems. This can be an error-prone and laborious process, especially if you must do this on several servers, each of which may have multiple databases.

Windows NT ships with a powerful pattern-searching utility called findstr, which can be used to greatly automate this task. It is even possible to conditionally execute a batch file based on whether certain error strings are found.

findstr uses Win32 asynchronous and file-mapped I/O for best throughput. It allows the use of regular expressions, recursive searching down a directory tree, and the ability to exclude patterns, thus achieving a NOT function. See your Windows NT documentation for more information.

There are two basic approaches to searching SQL error logs or DBCC output for errors:

  • State explicitly what strings to find.
  • State what strings you do not want to find.


findstr--Strings to Find

findstr—Strings to Find

In the first approach, you build a list of strings that define errors you want findstr to match. This list of strings can be supplied as an input file to the Findstr.exe file.

For example, say you want to find any occurrences of the strings "table corrupt," which accompanies many serious data errors, and "msg 605," which is a specific type of error. Place these strings into a file, called Search.txt, like this:

table corrupt
msg 605

Run Findstr.exe on the DBCC output files using the following syntax where Dbcc.* matches a group of DBCC output files to search, and Findstr.out is where the search results are placed:

findstr /i /g:search.txt dbcc.* > findstr.out

The challenge with this approach is knowing ahead of time what error strings to search for. Unfortunately, there is no comprehensive list of SQL error strings that encompasses all possible DBCC, server, and kernel errors. However, searching for the following strings provides fairly good coverage as a starting point:

level 16
Severity: 17
level 17
Severity: 18
level 18
Severity: 19
level 19
Severity: 20
level 20
Severity: 21
level 21
table corrupt
Severity: 16

Using a little experimentation, it is usually possible to further refine this and get fairly reliable checking.


findstr--Strings Not to Find

findstr—Strings Not to Find

The other approach involves using the reverse match capability of findstr to exclude a list of search strings. This approach is more easily applied to DBCC output than to error log output, since there are fewer distinct strings that require exclusion. In some ways this approach, if applicable, is safer, since you are only explicitly stating what not to match and any new or unanticipated errors are shown by default.

For example, say you want to exclude all strings in a series of DBCC output files that contain the strings "The total number," "Table has," and "checking." Experience indicates this will exclude many nonessential DBCC status messages and will not result in the loss of any errors. Place these strings into a file, called Search.txt, like this:

The total number
Table has
checking

Run Findstr.exe on the DBCC output files using the following syntax where Dbcc.* matches a group of DBCC output files to search, and Findstr.out is where the search results are placed:

findstr /v /i /g:search.txt dbcc.* > findstr.out

The /v parameter indicates reverse match, which effectively matches all strings except those in the list.

Here is a sample exclusion list for error logs that will filter out nonessential messages and allow most significant errors:

(id =
OS error : 109
1608
OS error : 232
17824
pipe name is
17825
Recovering Database
17832
recovery complete
Activating disk
Recovery dbid
All rights reserved
restrictions
clause
rolled forward
Clearing
server is unnamed
contracts
server name is
Copyright
shutdown by request
default character
SQL Server is start
default sort
subdivision
duplication
Sybase
file descriptors
terminating due
initconfig: number
transactions before ckpt
initializing virtual
transactions roll
initializing virtual
unable to read login
killed by hostname
unable to write to
Loading SQL Server
united states
Logging SQL Server
using asynchronous disk
network error
Using 'NTWDBLIB.DLL
network information
Using 'OPENDSNT.DLL
no_log
Using 'SQLEVENT.DLL
nocase
Using 'SSNMPNTW.DLL
number of buffers
windows nt
number of proc buffers
working thread
Opening Master Data

In some cases, combining these two approaches blends the best characteristics of both. At least, it allows you to work around difficult problems that arise from using just one.

For example, say you are searching your error logs for "Severity: 16," through "Severity: 21," which should match most serious errors. You notice in your search output several communication-related errors, such as 1608 and 17832, that are normally not indicative of a serious problem. You can keep your original search conditions and exclude only these specific unwanted errors from the search output by piping one findstr command into another using the following syntax where Search.txt is the file containing the search strings, Errorlog*.* matches a groups of SQL Server error log files to search, Exclude.txt is the file containing the search strings to exclude, and F.out is where the search results are placed:

findstr /i /g:search.txt errorlog*.* | findstr
/v /i /g:exclude.txt > f.out

This approach can be cascaded several levels deep, excluding successively more at each level.


Triggering a Batch File with findstr

It is possible to write a batch file that conditionally takes action based on whether findstr detects a certain error string. This technique uses the Windows NT conditional processing commands: && and ||. The following command executes the batch file Batch1.bat if any of the SQL error strings in the file Search.txt are found:

findstr /i /g:search.txt errorlog*.* && batch1

Batch1.bat could invoke a program or run an ISQL/w job that uses the extended stored procedure xp_sendmail to send a mail message notifying an operator of a problem.

The above techniques can be combined to perform a variety of tasks. For example, the following batch file will continuously run a findstr command that conditionally executes Batch1.bat if any of the SQL error strings in the file Search.txt are found, excluding the strings in Exclude.txt:

echo off
:start
findstr /i /g:search.txt errorlog*.* | findstr
/v /i /g:exclude.txt && (echo WARNING & batch1)
goto start

With a little experimentation, these techniques can reduce the labor involved in searching SQL Server error log files and DBCC output files. These same techniques can also be used for any general text-searching task, not just those related to SQL Server.

Note The Windows NT Resource Kit includes the powerful Perl scripting language, beginning with Windows NT 3.51. It's specifically designed for file scanning and batch automation. If you need more advanced batch automation and error-handling capabilities, you should strongly consider the Windows NT Resource Kit and Perl.

Starting with Windows NT 4.0, several powerful enhancements were added to the Cmd.exe command processor file that can facilitate writing patch jobs, especially those requiring conditional operations. One example is the FOR command. For details, run FOR/? or CMD/?.


Implementing Microsoft SQL Server

Implementing SQL Server on an optimized hardware platform entails configuring the system to take advantage of CPU, memory, disk subsystem, and network performance features.

This article discusses in detail performance-oriented installation options as well as performance-oriented configuration options and the effect of their use on SQL Server. In addition, some Windows NT options and considerations will be discussed, because they also affect SQL Server performance.


Windows NT Performance Options

The following Windows NT options affect SQL Server performance and should be configured before installing SQL Server.


Windows NT Task Management

Each application (as well as each thread) in the system has a set priority. You can set priorities system-wide from the System Properties dialog box, which is accessed by clicking System from Control Panel.

In Windows NT 4.0, the Performance tab looks like this.

Setting Boost to None affords SQL Server the best level of tasking and ensures that another application will not dominate the system.

In Windows NT 3.51, the System dialog box looks like this.

Setting this entry to Foreground and Background Applications Equally Responsive affords SQL Server the best level of tasking and ensures that another application will not dominate the system.


Boost SQL Server Priority

Boosting SQL Server's priority can improve performance and throughput on single- and multiple-processor hardware platforms because the Windows NT thread scheduler will favor SQL Server threads over threads of other processes. By default, this option is turned off and SQL Server runs at a priority of 7. When selected on a single processor platform, SQL Server runs at priority 15. When selected on an SMP platform, SQL Server runs at priority 24.

When this option is turned on, it can degrade the performance of other processes. Therefore, this option should only be turned on for dedicated SQL Server computers or if slower performance of other processes is acceptable.

Note Boost should generally not be used except in special circumstances.


Windows NT Server Resource Allocation

You can configure the server's resource allocation and associated nonpaged memory pool usage from the Network dialog box, which is accessed by clicking Network from Control Panel.

If you are using Windows NT 4.0, click the Services tab, click Server, and then click Properties.

If you are using Windows NT 3.51, click Server and then click Configure.

The Server dialog box appears.

Maximize Throughput for Network Applications is the optimal setting for a SQL Server system. With this option set, network-application access to memory has priority over file-cache access to memory. Four megabytes of memory is allocated to available memory for starting up and running local applications. In addition, the amount of memory allocated to the server service for the following resources is appropriately optimized for this choice:

  • BlockingThreads
  • InitWorkItems
  • MaxFreeConnection
  • MaxNonPagedMem
  • MaxPagedMemory
  • MaxWorkItems
  • MinFreeConnections
  • RawWorkItems
  • ThreadCountAdd


Windows NT Performance Considerations

The following Windows NT Server performance considerations should be addressed before installing SQL Server.


Windows NT Pagefile.sys Location

As previously stated, Windows NT memory management is handled by the Virtual Memory Manager (VMM). The VMM uses a system file, Pagefile.sys, for the storage of virtual memory pages. This file is typically stored in the root directory of a Windows NT system on the boot disk unit. This file can also be segmented as multiple files and stored on multiple disk units as an operating system performance enhancement.

With respect to SQL Server performance, this file should be stored on a physical disk unit that is segregated from the SQL Server disk units. Moreover, if the physical disk units are on separate intelligent controller units, all the better. This is especially true for nondedicated SQL Server systems, which are likely to experience moderate to heavy page faulting due to file and print sharing or application execution. However, you should recall it was recommended that only physical memory be allocated to SQL Server uses. Therefore, if you cannot map Pagefile.sys away from the SQL Server disk units, there should be little page faulting on dedicated systems as long as the memory allocation to Windows NT is sufficient (16 MB).


Windows NT File System Selection

Internal testing at Microsoft has shown that there is very little difference in SQL Server performance between NTFS and FAT file systems. In general, NTFS is faster than FAT for reads and slightly slower for writes, since it performs transaction logging for recoverability. The SQL Server TPC-B benchmarks published by Compaq used NTFS for the database devices and FAT for the log, since logging is write-intensive.

Note Both NTFS and FAT support Windows NT–based striping.


Windows NT Services

It is recommended that all services be turned off because services use valuable system resources and therefore potentially limit SQL Server performance. Candidates for disabling are:

  • Alerter
  • ClipBook Server
  • Computer Browser
  • Messenger
  • Network DDE
  • Network DDE DSDM
  • Schedule

In most cases, the following services should remain enabled:

  • EventLog
  • MSSQLServer
  • Server
  • SQL Executive
  • Workstation

You can turn off services from the Services dialog box, which is accessed by clicking Services from Control Panel.


Windows NT Network Protocols

Remove unused network protocols because their presence will negatively affect SQL Server performance.


SQL Server Installation Options

The following installation options affect SQL Server performance depending on their values.


SQL Server Installation Path

The SQL Server installation path (C:\Mssql by default) is where all the operational directories and files for the SQL Server system are written. For a marginal performance enhancement, do not place the SQL Server and operating system files on a disk unit or disk volume that will be subject to heavy database reading and writing.


Master Device Location

The location of the master device file, Master.dat, can be changed from the default path, C:\Mssql\Data, to any other system location. Consideration should be given to changing the location of this file to a dedicated physical disk unit or disk volume. This location will help to isolate database I/O away from system I/O. In addition, by default, the tempdb database, which is 2 MB in size, takes its initial space allocation from the master device.


Master Device Size

The master database device defaults to 25 MB in size. It is recommended that this be increased as needed to account for growth in the master database.


Character Set

The character set choice has no impact on SQL Server performance. However, if the character set differs between the client and the SQL Server, query results and/or execution can be unpredictable. The default is the ISO (8859-1) code page. For more information, see Microsoft SQL Server Setup.


Sort Order

Binary sort order is the fastest sort order option. The following table shows the approximate decrease in sort order performance, relative to binary order, for each sort order. The operation evaluated involved string comparisons on character fields.

Sort order | Percent slower
Dictionary order, case-sensitive | 20%
Dictionary order, case-insensitive, uppercase preference | 20%
Dictionary order, case-insensitive (no uppercase preference) | 20%
Dictionary order, case-insensitive, accent-insensitive | 35%

The percentages in the table are approximate. The overall performance difference between sort orders varies significantly depending on the types of operations and the types of data used. For more information, see Microsoft SQL Server Setup.


SQL Server 6.5 Setup: Server Options

The SQL Server Setup program allows for the selection of two options that affect the priority at which SQL Server threads run, thereby influencing system performance. These options can be found in the Select Server Options dialog box, which is accessed by clicking the Set Server Options installation option of the Setup program.


SQL Server Configuration Options

The following SQL Server configuration parameters impact performance or performance-related resources. Each configuration parameter is defined with respect to its function and its impact on performance.

  • Memory—On computers with 32 MB or less, you should generally allocate at least 8 MB to 16 MB to Windows NT and configure SQL Server to use the rest. For computers with more than 32 MB, allocate 16 MB to 20 MB to Windows NT and allocate the rest of the memory to SQL Server.

    Performance impact—Physical memory is used by SQL Server for server operation overhead, data (buffer) cache, and procedure cache. Therefore, to reduce SQL Server page faults, an appropriate amount of memory should be configured.

  • Max async IO—The max async IO parameter controls the number of outstanding asynchronous batch writes performed by checkpoint and lazy writer. The default is eight, and this is likely to be sufficient in most cases. However, you may want to experiment with this number to try to improve performance. Increasing the parameter allows more asynchronous batch writes to be performed, effectively shortening the period that the system is checkpointing or doing lazy writing. However, if your I/O subsystem cannot sustain the increased write activity, the increased writes will flood the I/O systems and can interfere with the ability of SQL Server or other processes to read from the disk, resulting in decreased throughput. The behavior of this parameter is therefore dependent to a large degree on the underlying I/O subsystem.

    Performance impact—SQL Server for Windows NT uses the asynchronous I/O capability of the Windows NT operating system, which includes the Win32 API calls ReadFile(), ReadFileEx(), WriteFile(), and WriteFileEx(). For more information, see the Win32 SDK. Asynchronous, or overlapped I/O, refers to the ability of a calling program to issue an I/O request without waiting for completion to continue with another activity. When the I/O finishes, the operating system will notify the program by using a callback or other Win32 synchronization mechanism.

    This has two main advantages. First, it makes implementation easier for an application designer, since the operating system can be used to perform asynchronous I/O rather than having to simulate this capability in the application. Second, the multiple outstanding I/O requests can drive certain high performance disk subsystems at greater performance levels than would be otherwise possible. This is generally only possible with very high-performance, intelligent, disk subsystems because only these types of systems have the specific features necessary to rapidly accept multiple asynchronous I/O requests from a Win32 application such as SQL Server.

    On these systems, increasing the max async IO parameter of SQL Server can result in performance improvements during very disk-intensive operations. The actual setting used for this parameter and the resultant performance increase will vary depending on the exact hardware and database I/O profile. It should not be set arbitrarily high, since inordinate asynchronous I/O consumes system resources.

  • Working set—You can set Windows NT to reserve physical memory space for SQL Server equal to the sum of the memory setting and the size of tempdb if it is in RAM. The values are 0 (no working set, the default) and 1 (working set).

    The set working set size parameter (set with sp_configure or SQL Enterprise Manager) can disable the locking of memory as a working set. If "out of memory" errors occur, you may have too much memory assigned to SQL Server.

  • Sort pages—Specifies the maximum number of pages that will be allocated to sorting per user. The default is 64. On systems that perform large sorts, increasing this number can improve performance. Since additional sort pages consume memory, increasing this value can make it necessary to increase the amount of memory dedicated to the server. The minimum value is 50 and the maximum value is 511.
  • Hash buckets—Sets the number of buckets used for hashing pages to buffers in memory. If the value specified is not a prime number, the closest prime number is used. For example, specifying 8,000 creates 7,993 hash buckets (the default). On systems with a large amount of memory, this value can be increased to allow faster access to data residing in data cache. For systems with 160 MB or less, 7,993 is an appropriate value and the default. This option does not take effect until the server is stopped and restarted. The minimum value is 4,999 and the maximum value is 26,500.
  • Procedure cache—By default, 30 percent of the available memory is reserved for the procedure cache. In systems with large amounts of memory, this is often excessive.

    Performance impact—Having a properly-sized procedure cache results in fewer page faults with respect to use of stored procedures, triggers, rules, and defaults.

  • User connections—Sets the maximum number of simultaneous connections to SQL Server. The actual number of connections may be less depending on your database environment. The maximum value for this parameter is 32,767. However, this value must be set based upon available memory and application requirements.

    Performance impact—Each user connection requires 40K of memory. Therefore, increasing user connections will increase the amount of memory needed for SQL Server overhead, thereby reducing the memory available for the data (buffer) and procedure caches. Worker threads is another fixed cost. Each allocated thread deducts from the memory available for procedure and data cache. Consequently, more physical memory may be required to maintain cache performance levels.

  • Open databases—This value sets the maximum number of databases that can be open at one time on SQL Server. The default is 20; this value can be set as high as 100.

    Performance impact—Each open database resource consumes 650 bytes of memory. Therefore, increasing the number of open databases increases the amount of memory needed for SQL Server overhead, thereby reducing the memory available for the data (buffer) and procedure caches. Consequently, more physical memory may be required to maintain cache performance levels.

  • Locks—The locks parameter sets the number of available locks for SQL Server. Locks are used for concurrency control. The default value is set at 5,000 locks.

    Note You should consider increasing the lock value to 10,000.

    Performance impact—Each lock consumes 60 bytes of memory. Therefore, increasing the number of locks will increase the amount of memory needed for SQL Server overhead, thereby reducing the memory available for the data (buffer) and procedure caches. Consequently, more physical memory may be required to maintain cache performance levels.

  • Open objects—The open objects parameter sets the number of database objects that can be open at one time on SQL Server. The default is 500.

    Note You should not hesitate to increase the open objects value to 1,000 for many situations; consider increasing it to as high as 5,000.

    Performance impact—Each open object requires 240 bytes of memory. Therefore, increasing the number of open objects will increase the amount of memory needed for SQL Server overhead, thereby reducing the memory available for the data (buffer) and procedure caches. Consequently, more physical memory may be required to maintain cache performance levels.

  • Fill factor—The fill factor determines how full SQL Server will make each index page when creating new indexes. The default value is 0.

    Performance impact—The fill factor percentage affects SQL Server performance because SQL Server must split an index page when it becomes full. Thus, maintaining a small fill factor on an index that is associated with a very dynamic table results in fewer page splits, fewer index entries per page, and a longer index page chain. Conversely, a high fill factor on a read-only table is perfectly acceptable and results in full index pages and a shorter index page chain.

  • Time slice—The time slice parameter sets the number of times a user process is allowed to pass through a yield point without voluntarily yielding to the next process.

    Performance impact—If time slice is set too low, SQL Server will spend too much time switching between processes. Conversely, if time slice is set too high, waiting processes can experience long response times. The default of 100 is generally adequate and should seldom be changed.

  • Max worker threads—This parameter allows you to control the number of threads allocated to the pool of user threads. This can be useful when you have hundreds or thousands of user connections to SQL Server, where the overhead of managing hundreds or thousands of operating system threads would impair performance. When you limit the number of SQL Server working threads, user requests are executed on the next available worker thread. This parameter defaults to 255 and can be increased to 1,024.

    Note Do not change this value from its default except when you are directed to do so by your primary support provider.

  • Tempdb in RAM—This option can improve performance when processing involves sorting, group by, or joins without supporting indexes. Allocating memory to tempdb effectively reduces the amount of memory available to allocate to the SQL Server data cache. Accordingly, you need enough physical memory to store the entire tempdb in RAM without impacting the memory required for Microsoft Windows NT Server, SQL Server, and applications. Thus, you should only consider using tempdb in RAM when you have large amounts of memory available. The default is off (0).

    Performance impact—Forcing tempdb into RAM can result in increased performance if a significant amount of processing involves the creation and use of worktables by the SQL Server optimizer. Execution of such processing in RAM is inherently faster than corresponding disk I/O from paging.

  • Recovery interval—Sets the maximum number of minutes per database that SQL Server needs to complete its recovery procedures in case of a system failure. In addition, this value is used along with the amount of activity on each database to calculate when to do a checkpoint on each database.

    Performance impact—With the lazy writer process available in SQL Server, it is not necessary to tune the checkpoint interval for optimum performance. In fact, you can set the recovery interval very high to ensure that checkpointing occurs infrequently when performance is important. Remember however, that increasing the period between checkpoints also increases the time SQL Server takes to perform automatic recovery when the database is restarted after an ungraceful shutdown (power failure, hardware failure, and so on).

When configuring your SQL Server, start with the default values and experiment with changing parameter values once you have obtained a baseline of performance. When adjusting parameters to tune performance, adjust one parameter at a time and measure the difference in performance; changing multiple parameters in an ad hoc fashion is generally not productive.


Other Performance Considerations

The following database options and SQL Server performance considerations are vitally important with respect to optimal SQL Server operation.


trunc. log on chkpt.

Don't use trunc. log on chkpt. This causes a checkpoint and transaction log dump to occur every minute and will adversely affect performance.


Lazy Writer

The lazy writer's main task is to flush out batches of dirty, aged buffers—buffers that contain changes that must be written back to disk before the buffer can be reused for a different page—and make them available to user processes. The batch I/O size used by lazy writer can be set by the max async IO parameter using the sp_configure stored procedure. This parameter controls both the checkpoint's and lazy writer's batch I/O size and can be tuned to maximize the I/O throughput for specific hardware platforms and I/O subsystems.

The lazy writer process automatically starts flushing buffers when the number of available free buffers falls below a certain threshold and stops flushing them when this number goes approximately 5 to 6 percent above the threshold. This threshold value is specified as a percentage of total number of buffers in the buffer cache.


Tuning

After you've applied optimization guidelines, tuning is a snap.

Tuning the SQL Server solution should be much less difficult at this point since we have applied optimization guidelines throughout the solution development process. However, reality dictates that no implementation is performance perfect. Consequently, the following article consists of tuning strategies previously discussed. A prior understanding of the Windows NT Performance Monitor is required to apply some of the tuning strategies presented.

It is beyond the scope of this article to address every possible tuning situation. Therefore, only those scenarios that have the greatest impact on performance will be discussed.

All monitoring requires the use of the Windows NT Performance Monitor unless otherwise specified. In addition, all guidelines apply to dedicated SQL Server systems. However, these techniques can be applied to nondedicated SQL Server systems with only slight modification.


Hardware Resource Tuning

The tuning of hardware resources typically involves the discovery of bottlenecks. A bottleneck is the single resource that consumes the most time during a task execution. In the case of SQL Server, such resource bottlenecks adversely affect the performance of normal relational database operations. Therefore, the following information pertains to the detection of SQL Server resource bottlenecks and the subsequent adjustment of the resource to relieve the demand and increase performance.


Processor Tuning

Processor tuning involves the detection of CPU-bound operations. The following processor bottleneck monitoring guidelines will aid in determining such problems.

Symptoms and Actions

  • Symptom: If Processor: % Processor Time consistently registers in the range of 80 percent to 100 percent, the processor(s) may be the bottleneck. (System: % Total Processor Time can be viewed for multiprocessor systems.)

    Action: Determine which SQL Server User process is consuming the CPU. To determine which process is using up most of the CPU's time, monitor SQLServer-Users: CPU time for all of the process instances (spid). One or more will appear as using the greatest cumulative time. Having determined the offending process instance, examine the query for inefficient design. In addition, examine indexes and database design for inefficiencies with respect to excessive I/O that consumes CPU cycles. (Wide tables and indexes as well as table scans cause more I/Os to occur.)

  • Symptom: If Processor: % Privileged Time is consistently over 20 percent and Processor: % User Time is consistently below 80 percent, then SQL Server is likely generating excessive I/O requests to the system.

    Action: Examine the disk controller card and the network interface card (see "General Actions for Processor Tuning" later in this article). In addition, if this is not a dedicated SQL Server system, look for other processes that meet the above criteria by using Process: % Privileged Time and Process: % User Time. If you find such processes, eliminate them, or schedule them to run at more convenient times.

General Actions for Processor Tuning

  • Excessive processing may indicate a need to further denormalize the database.
  • Schedule CPU-intensive queries during off-peak hours.
  • Investigate tuning the query to be less CPU intensive (see "Query and Index Tuning" in Part 3).
  • Boost the SQL Server priority as previously discussed.
  • Determine that no unnecessary processes are running on the SQL Server platform. If so, turn them off to see if this improves performance.
  • Set Windows NT Tasking to Foreground and Background Applications Equally Responsive.
  • Assuming you have at least a 486-based server, part of the problem may be the network or disk adapter cards. 8-bit cards use more processor time than 16-bit or 32-bit cards. (The number of bits refers to the amount of data moved to memory from the adapter on each transfer.) The most efficient cards use 32-bit transfers to adapter memory or direct memory access (DMA) to move their data. Adapters that don't use memory-mapped buffers or DMA must use processor instructions to move data, and that makes the processor busy. DMA uses memory, which can slow the processor down, but it is still more efficient than individual instructions.
  • Placing tempdb in RAM may help by reducing I/O requests.
  • Assuming that SQL Server has sufficient memory to run (see "Memory Tuning," later in this article), increasing CPU power is the most effective hardware-related way to improve performance. You can add CPU power in two ways: using a faster CPU, or adding additional CPUs.
    • Faster CPU: When performance is important, you should consider using as fast a CPU as possible. In general, a faster CPU will probably realize a bigger performance gain over adding an additional CPU. This is because, while adding CPUs provides additional power, the operating system and SQL Server (or any application) incur an overhead in managing the work performed by multiple CPUs. Of course, once you are running the fastest CPU available in your chosen architecture, you can add additional CPUs to increase performance.
    • Additional CPUs: Windows NT supports symmetric multiprocessing (SMP). Since SQL Server is implemented using native Windows NT threads, it can automatically take advantage of multiple CPUs. SQL Server takes good advantage of SMP platforms. To boost performance significantly, move your application to an SMP platform or add additional CPUs to an existing SMP platform.


Memory Tuning

Memory tuning involves the detection of memory-constrained operations. The following memory bottleneck-monitoring guidelines will aid in determining such problems.

Symptoms and Actions

  • Symptom: If the SQLServer: Cache Hit Ratio is less than 80 percent, memory may be a bottleneck.

    Note Be advised that the SQLServer: Cache Hit Ratio in Performance Monitor is an average calculated since boot time, not the value over the last n seconds. Therefore, if many data points accumulate, the graph will only sluggishly change to varying conditions.

    Action: Either allocate more memory to SQL Server or increase the amount of system memory.

  • Symptom: If the SQLServer: I/O - Lazy Writes/sec counter indicates a great deal of activity over a long interval of time, then a memory bottleneck may be indicated. Typically, this counter should be zero until the LRUthreshold (default 3 percent) is reached with respect to free buffer pages. However, frequent activity may indicate not enough memory is available for data-page caching.

    Action: Compare the SQLServer: Cache - Number of Free Buffers value against the LRUthreshold value. This value is derived by obtaining the total number of buffers allocated by the DBCC MEMUSAGE statement and multiplying this number by the LRUthreshold percentage. If the number of free buffers is close to the derived value then either allocate more memory to SQL Server or increase the amount of system memory.

  • Symptom: If Memory: Page Faults/sec is consistently high (other than during SQL Server initialization), then not enough memory is dedicated to Windows NT or possibly the system as a whole.

    Action: Increase the system memory or increase the memory dedicated to Windows NT by decreasing the memory allocated to SQL Server or other processes. You can also eliminate noncritical processes because these also use memory resources.

  • Symptom: If SQLServer: I/O - Page Reads/sec is consistently high, it may indicate a memory bottleneck. Typically, if enough memory is available for database activities during normal operations, this counter will generally reach an equilibrium point. However, if this counter remains high over a long time interval, lack of sufficient memory may be causing excessive SQL Server page faults. This may be due to a less than adequate data cache, poor index design, or poor database design.

    Action: Increase the memory allocated to SQL Server or decrease the procedure cache percentage, thereby increasing the data cache. If indexes are not being used, design intelligent indexes. If database tables are too wide (resulting in fewer data rows per data page), redesign the tables to be narrower.

  • Symptom: If SQLServer: Cache - Avg. Free Page Scan or SQLServer: Cache - Max. Free Page Scan are over 10, a memory bottleneck may be indicated due to excessive buffer scanning while searching for a free page.

    Action: Increase the data cache size or the frequency of checkpoints. Checkpoints can be increased by decreasing the recovery interval value or by manual execution.

General Actions for Memory Tuning

  • Check the amount of memory dedicated to SQL Server by using the SQL Server configuration options. Follow the memory allocation guidelines previously discussed, increasing memory appropriately. Allocate at least 16 MB to Windows NT.

    Note Although the memory allocation for keeping tempdb in RAM is not part of the memory configuration value, it may reduce the system memory available for the data and procedure cache.

  • Make sure the Pagefile.sys file is of adequate size. However, it should not be growing in size; this would indicate that virtual memory requirements are exceeding capacity. On a dedicated SQL Server system, there should be virtually no paging as long as Windows NT has been allotted sufficient memory (at least 16 MB).
  • If you make extensive use of extended stored procedures, you should unload the DLL after execution by using the DBCC dllname(FREE) statement. This releases the memory used by the DLL.


Disk Subsystem Tuning

Disk subsystem tuning involves the detection of disk I/O–constrained operations. Such bottleneck constraints can be caused by the disk controller, the physical disk drives, or lack of some other resource, which results in excessive disk I/O–generating activity. Furthermore, poor disk subsystem performance can also be caused by poor index or database design. The goal is to operate the SQL Server with as few physical I/Os and associated interrupts as possible. The following disk I/O bottleneck-monitoring guidelines will aid in achieving this goal.

Note To monitor low-level disk activity with respect to the PhysicalDisk Performance Monitor counters, it is necessary to enable the diskperf option. To enable the diskperf option, issue the following command from the command prompt: diskperf -y.

When performance tuning the SQL Server disk subsystem, you should first attempt to isolate the disk I/O bottleneck with the SQLServer counters, and then use the PhysicalDisk and LogicalDisk counters for more detailed monitoring and refinement of an action plan.

Symptoms and Actions

  • Symptom: If SQLServer: I/O - Lazy Writes/sec is active for extended intervals, this may indicate that the disk subsystem is not adequate with respect to the current I/O demands. (Also see "Memory Tuning," earlier in this article.)

    Action: Observing either LogicalDisk: Current Disk Queue Length or PhysicalDisk: Current Disk Queue Length can reveal significant disk congestion. Typically, a value over 2 indicates disk congestion. Increasing the number of disk drives or obtaining faster drives will help performance.

  • Symptom: If SQLServer: I/O - Outstanding Reads and/or I/O - Outstanding Writes are high for extended intervals of time, the disk subsystem may be a bottleneck.

    Action: Observing either LogicalDisk: Current Disk Queue Length or PhysicalDisk: Current Disk Queue Length can reveal significant disk congestion. Typically, a value over 2 indicates disk congestion. Increasing the number of disk drives or obtaining faster drives will help performance.

  • Symptom: If SQLServer: I/O - Log Writes/sec seems to reach a maximum level, you may have encountered the maximum sequential write capability of the disk drives in the system. You will see this occur most frequently on systems that have a dedicated disk drive for logging. On systems without a dedicated log disk drive, you will observe a greater number of outstanding I/O requests as discussed previously.

    Action: Obtaining faster disk drives or disk controllers will help to improve this value.

General Actions for Disk Subsystem Tuning

  • If you have a disk subsystem that supports asynchronous I/O (one that supports disk arrays and/or includes a smart SCSI controller), you may consider increasing the max async IO option (default 8) to obtain higher throughput. To determine if higher throughput is gained, monitor SQLServer: I/O - Batch Writes/sec before the change to max async IO and after the change. You should also notice an increase in the value of SQLServer: I/O Transactions/sec. This assumes the current physical disks are not experiencing I/O congestion. In addition, increasing the max async IO value (maximum value is 255) may result in excessive overhead.
  • Install a faster disk and/or controller. Determine if the controller card does 8-bit, 16-bit, or 32-bit transfers. The more bits in the transfer operation, the faster the controller moves data. You may also want to choose a different drive technology, such as integrated drive electronic (IDE) which has a 2.5 MB/sec throughput; ESDI, which has a 3 MB/sec throughput; SCSI-2, which has a 5 MB/sec throughput; or a Fast SCSI-2, which has a 10 MB/sec throughput.
  • Create mirrored data sets. The I/O system can issue concurrent reads to 2 partitions. The first portion of the read will be to partition A, while the next portion of the read will be to partition B. (Assuming the disk driver and controller can handle asynchronous I/O.)
  • Create striped data sets. Multiple disks can process I/O requests concurrently (assuming the disk driver and controller can handle asynchronous I/O).
  • Add memory to increase the data cache size, thereby decreasing physical page reads.
  • Use a fast I/O bus architecture like PCI. PCI is a faster bus architecture than ISA bus architecture.
  • When choosing an I/O controller, consider its performance characteristics.
  • On a 2 SCSI disk daisy-chained system, the SCSI controller has more of an impact on your total performance than your disk drive. You would be better off buying a slower, cheaper disk and investing in a better SCSI controller.
  • Choose a disk with a low seek time (the time required to move the disk drive heads from one track of data to another). The ratio of time spent seeking to time spent transferring data is usually 10 to 1, and often much higher.
  • Distribute the workload as evenly as possible among different I/O systems and disk drives. This will allow you to take full advantage of system I/O bandwidth.


Network Tuning

Network tuning with respect to SQL Server performance is affected by the following:

  • Throughput of the LAN or WAN.
  • Throughput of the server network interface card.
  • Availability of resources on the server to service client requests.

The throughput of the LAN or WAN is not critical to the tuning of a specific SQL Server. However, when considering remote procedure calls between SQL Servers or data replication, LAN and/or WAN throughput will be an important concern. Thus, this section will deal with tuning issues related to the network interface card and system or SQL Server resources that affect the SQL Server's network performance. Accordingly, the following network bottleneck-monitoring guidelines will deal with these issues.

Symptoms and Actions

  • Symptom: On a dedicated SQL Server system, if SQLServer: NET - Network Reads/sec is substantially lower than Server: Bytes Received/sec, this may indicate network activity beyond that generated by SQL Server. This may also be caused by periodic Windows NT Server administrative processes if the system also serves as a primary domain controller (PDC) or backup domain controller (BDC).

    Action: Determine if any processes or protocols extraneous to the operation of SQL Server are running. If so, stop them.

  • Symptom: On a dedicated SQL Server system, if SQLServer: NET - Network Writes/sec is substantially lower than Server: Bytes Transmitted/sec, this may indicate network activity beyond that generated by SQL Server. This may also be caused by periodic Windows NT Server administrative processes if the system also serves as a PDC or BDC.

    Action: Determine if any processes or protocols extraneous to the operation of SQL Server are running. If so, stop them.

  • Symptom: If SQLServer: NET - Network Reads/sec or SQLServer: NET - Network Writes/sec is high this indicates a great deal of network traffic.

    Action: Look at the number of SQLServer: User Connections and the SQLServer: Net - Command Queue Length. If these values are also high, especially Net - Command Queue Length, then consider increasing the memory allocated to SQL Server. However, you may want to restrict user connections with sp_configure to decrease the workload on the SQL Server. Remember, user connections and worker threads are counted as overhead against the SQL Server memory allocation. Thus, plan accordingly when adjusting these values.

General Actions for Network Tuning

  • Tabular data stream (TDS) is the application protocol used by SQL Server for the transfer of requests and request results between clients and servers. TDS data is sent in fixed-size chunks, called packets. TDS packets have a default size of 512 bytes. If an application does bulk copy operations or sends or receives large amounts of text or image data, a packet size larger than 512 bytes may improve network performance, since it results in fewer reads and writes. For large data transfers, a packet size between 4,092 and 8,192 is usually best. Any larger size packet may degrade performance.

    To set the server's default packet size, set network packet size in sp_configure. Packet size can be configured in ISQL/w for the current ISQL/w connection only. Configuring the packet size gives you a choice between responsiveness and overall throughput. Larger packets provide less packet overhead and provide better end-to-end throughput: An entire task completes more quickly with larger packets. Smaller packets are more responsive for those interested in intermediate results. Overall, a smaller packet size provides quicker response time, but usually, an entire task takes longer to complete with smaller packets than with larger packets. For more information about configuring packet size, see SQL Server Books Online.

    You can monitor the improvement in network read and write efficiency by viewing the SQLServer: NET - Network Reads/sec and SQLServer: NET - Network Writes/sec counters before and after changing the TDS packet size. Fewer reads and writes should occur after increasing the packet size.

  • Make sure the server throughput is set to Maximize Throughput for Network Applications; this is the default for SQL Server. However, with this option set, user application access has priority over file cache access to memory (4 MB of memory is allocated to available memory for starting up and running local applications).
  • Increase update-notice periods for Netlogon service on the SQL Server if your SQL Server is a PDC. Also increase the server announcement period if you are concerned with the amount of maintenance traffic the Windows NT Server is creating and the load on the PDC.

Value name | Default value | Minimum value | Maximum value
PulseConcurrency | 20 | 1 | 500
Pulse | 300 (5 minutes) | 60 (1 minute) | 3600 (1 hour)
Randomize | 1 (1 second) | 0 (0 seconds) | 120 (2 minutes)

  • PulseConcurrency defines the maximum number of simultaneous pulses the PDC sends to BDCs.

    Netlogon sends pulses to individual BDCs. The BDCs respond by asking for any database changes. To control the maximum load these responses place on the PDC, the PDC will only have PulseConcurrency pulses "pending" at one time. The PDC should be sufficiently powerful to support this many concurrent replication RPC calls (related directly to Server service tuning as well as the amount of memory in the computer).

    Increasing PulseConcurrency increases the load on the PDC. Decreasing PulseConcurrency increases the time it takes for a domain with a large number of BDCs to get a SAM/LSA change to all of the BDCs. Consider that the time to replicate a SAM/LSA change to all the BDCs in a domain will be greater than: ((Randomize/2) * NumberOfBDCsInDomain) / PulseConcurrency

  • Pulse defines the typical pulse frequency (in seconds). All SAM/LSA (User/Security account database) changes made within this time are collected together. After this time, a pulse is sent to each BDC needing the changes. No pulse is sent to a BDC that is up-to-date.
  • If you need to transfer huge amounts of data between different computer systems, Ethernet may not be the appropriate medium to use; the basic Ethernet cable is limited to 10 MB/sec (considerably less when you include network overhead). Other media are now available that offer significantly higher sustained transfer rates (FDDI, ATM, and so on).
  • The Network Monitor (provided with Microsoft Systems Management Server) is a good tool to use to monitor general network performance. It offers additional Performance Monitor counters as well as a few unique statistics from within the application.
  • Match the network interface card to the system bus. If you have a 16-bit bus, use a 16-bit network adapter; if you have a 32-bit bus, use a 32-bit network adapter. In addition, the card should be a bus master card to minimize the processing overhead associated with network interrupts.


SQL Server Tuning

Tuning the SQL Server involves appropriately adjusting the SQL Server configuration, options, and setup values based on observed operational characteristics. Typically these observations are made during peak work cycles to optimize for the heaviest work loads. The following tuning recommendations are those that generally have the greatest impact on SQL Server performance. However, application of these recommendations may result in different outcomes depending on your particular SQL Server environment.


Memory

As previously discussed, SQL Server memory is divided between SQL Server overhead, the procedure cache, and the data cache. The primary goal is to cover SQL Server overhead while effectively distributing the remaining memory between the procedure and data cache by using the procedure cache configuration parameter. The distribution of the remaining memory between these caches is an exercise in making sure the most-used objects are cached in their respective caches. Therefore, the most-used stored procedures should be in the procedure cache, while the majority of frequently used indexes and tables should be in the data cache.

The best way to determine how memory is being used by SQL Server is to execute DBCC MEMUSAGE. This statement indicates the amount of memory allocated to SQL Server at startup, the 12 largest objects in the procedure cache, and the 20 largest objects in the data cache. Therefore, the following recommendations are based upon the use of this data and will aid in determining the optimal size for these caches.


Tuning the Procedure Cache

When tuning the procedure cache, the goal is to determine the optimal size for the purpose of holding the most active stored procedures as well as the other procedure cache data objects. In essence, you want to prevent reading stored procedures from the disk because this is very costly. Moreover, if the procedure cache is large enough, it will prevent the displacement of procedures in the cache by procedures not yet in the cache. (Remember that the SQL Server will store a duplicate copy of each stored procedure execution plan that is accessed by more than one user.) By default, SQL Server distributes 30 percent of available memory to the procedure cache after SQL Server overhead has been allocated. The task is to determine if this 30 percent is sufficient, not enough, or too much based on the size of procedure cache objects.

Note Do not decrease the procedure cache below 5 percent.

You can determine if the procedure cache is large enough by executing the most frequently used stored procedures and then running the DBCC MEMUSAGE statement; the 12 largest stored procedures in the procedure cache will be displayed. If you have more than 12 stored procedures, you can continue to execute the other procedures, checking each time with the DBCC MEMUSAGE statement to see if one of the previously executed procedures has remained cached. You can also execute each stored procedure, obtaining its execution plan size by using the DBCC MEMUSAGE statement. Once you have executed all high-frequency procedures and obtained their sizes, add these size values to derive the total cache size necessary for all procedures.


Tuning the Data Cache

The data cache is composed of the memory left after SQL Server overhead and the procedure cache memory requirements have been satisfied. The goal is to have enough cache space to hold the majority of all indexes used and a respectable percentage of the most frequently accessed tables, thus reducing physical I/Os.You may also use the DBCC MEMUSAGE statement to view the 20 largest objects in the data cache. Again, you can use this data to determine a respectable size for the data cache based on the sizes indicated for these 20 database objects. You can also determine the size of the most frequently accessed tables and indexes by applying the size formulas given in Appendix A of the Microsoft SQL Server Administrator's Companion. Having calculated these sizes, you may elect to allocate enough memory to SQL Server to contain the entirety of these database objects in the data cache.


tempdb in RAM

If the queries being executed against the SQL Server are using temporary workspace for sort operations, GROUP BY, temporary tables, multitable join operations, and so on, it will be beneficial to move tempdb to RAM. However, to make this move, you must have available memory beyond that required by and allocated to Windows NT Server and SQL Server. Consequently, if the tempdb is currently 25 MB in size, then the total memory required for the system is: 16 MB for Windows NT Server plus total SQL Server memory plus 25 MB for tempdb.


Database Tuning

The database tuning process is based on performance observations gathered during normal SQL Server operations, typically at the time of peak work cycles. Symptoms indicating that possible database tuning may be necessary usually consist of excessive disk I/O and/or excessive cache flushes. Both of these symptoms have been addressed earlier with respect to memory and disk I/O tuning. However, assuming that these SQL Server resources have been sufficiently tuned, it is now time to examine the database design and the mapping of the physical database to physical disk devices.


Redesigning Tables

The following conditions are those that would dictate table redesign:

  • Condition: The tables are very wide, resulting in fewer data rows fitting on a data page. Therefore, the data page chain is very long and requires a larger data cache to hold all required data. In addition, this circumstance can cause excessive physical page reads due to data cache limitations.

    Action: Such tables are candidates for normalization or vertical segmentation, which results in smaller tables and a greater number of data rows per data page. Therefore, data retrieval performance should improve, provided the data cache is sufficient. If this action is taken, be sure to account for the new design with respect to updates, inserts, and deletes.

  • Condition: The tables are huge, containing many rows of data. Therefore, not all relevant data can fit into the available data cache, resulting in excessive physical page reads from disk.

    Action: Such tables are candidates for horizontal segmentation. Horizontal segmentation is most beneficial when only a subset of the data is normally accessed. In addition, fewer rows per table results in faster retrievals when a table scan is involved. If this action is taken, be careful to account for the new design with respect to updates, inserts, and deletes.


Remapping the Database

The following conditions are those that would lead you to consider remapping the database to take advantage of more efficient disk I/O. However, such remapping means physically rebuilding the database. Therefore, the recommended actions should be considered carefully before proceeding.

  • Condition: Queries against a table that is very large and that resides on the same physical device(s) or default segment as other frequently accessed tables is experiencing slow retrieval due to disk I/O congestion.

    Action: Placing the table on a SQL Server segment that is mapped to a database device on one or more dedicated physical drives can improve performance. In fact, if the database device is mapped to a RAID 0 or RAID 5 partition that is controlled by using a dedicated intelligent array controller, performance can be substantially increased. However, the creation of segments carries with it the potential for high administrative costs. Therefore, it may be more cost effective to simply enhance the disk subsystem components.

  • Condition: Queries against a very large table that resides on the same physical device(s) or default segment as its most frequently used index are experiencing slow retrieval due to disk I/O congestion.

    Action: If multiple databases are on the same device, consider moving some of the databases to other devices.


SQL Executive Troubleshooting

Keep the SQL Executive component of SQL Server running smoothly.

The SQL Executive component of SQL Server provides powerful scheduling capabilities that enable replication. With SQL Executive, you can schedule backups, DBCC operations, and administrative maintenance tasks. There are several reasons why SQL Executive might stop running or executing tasks.


SQL-DMO Error Message 1722

If, at any time, you have changed the Windows NT computer name but not the SQL Server name and the @@SERVERNAME global variable is not NULL and does not match the Windows NT computer name, then you must change the SQL Server name using sp_dropserver and sp_addserver. For more information, see SQL Server Books Online.

To get the registered SQL Server name, execute the statement:

SELECT @@SERVERNAME

Or you can view the server name in the SQL Server error log located in the \Mssql\Log directory. The SQL Server name must also conform to the rules for identifiers.


Logon Account

In SQL Executive, you can log on under "system account" or "other account."

It is generally recommended that you create a user account in the Domain\Administrators group.

On the Start menu in Windows NT 4.0, point to Programs and then Administrative Tools. Click User Manager for Domains.

On the User menu, click Select Domain.

Type the SQL Server name in the Domain box and click OK.

On the User menu, click New User.

Type the following information:

Username: SQLServer

Full Name: SQL Server admin account

Description: SQL Server administration account

Password : (enter password for account)

Confirm Password: (enter password again)

Make sure only the following check boxes are selected:

User Cannot Change Password

Password Never Expires

A frequent cause of failure in this situation is that the account SQL Executive is using has a password that has expired or changed. If this is the case, perform the following:

On the Start menu in Windows NT 4.0, point to Settings and then click Control Panel.

Double-click Services.

Click SQL Executive and then click Startup.

Enter the correct account and password information for SQL Executive and click OK.

Click Start to restart the SQL Executive service.


Local Group Membership

If SQL Executive is logging on as "other account," verify that the account is a member of the administrator group on the local computer. If the account you are using is not a member of the local administrator group, add it to the administrator group so that SQL Executive will be able to log on properly.

On the Start menu in Windows NT 4.0, point to Programs and then Administrative Tools. Click User Manager for Domains.

On the User menu, click Select Domain.

Type the SQL Server computer name in the Domain box and click OK.

Click Administrators in the Groups box, then on the User menu, click Properties.

Click Add.

Type the account name in the Add Names box and click OK.

If you are still having problems getting SQL Executive to log on properly, there is probably a permissions restriction in the Registry.

Execute Regedt32.exe and go to the following locations:

HKEY_LOCAL_MACHINE on Local Machine

\SOFTWARE

\MICROSOFT

\MSSQLServer

\SQL Executive

and

HKEY_LOCAL_MACHINE on Local Machine

\SYSTEM

\CurrentControlSet

\Services

\SQL Executive

Select a folder in one of these directories.

On the Security menu, click Permissions.

Check to see that the administrator's group and local system account have full control of the SQL Executive folders.

If you still receive errors, such as 109 or 1069, when starting SQL Executive, you can rebuild the Registry for SQL Server.


Rebuilding the Registry for SQL Server

To rebuild the SQL Server registry entries, open a command prompt. The following commands will run the Setup program to rebuild the Registry.

The options to the Setup program are case-sensitive and must be typed exactly as shown. Also, a space must be on both sides of the equal sign (=). This example assumes that SQL Server version 6.5 was installed on drive C:.

cd \mssql\binn
   setup /t RegistryRebuild = On

Note You can use = On or = True for the setup line.

You now must answer the questions exactly as you did during installation. The Setup program will reinsert all of the entries into the Registry but will not install or change any files.

If SQL Server was set up to use integrated security, you will need to re-add all of the users and groups by using the SQL Security Manager. You should re-add all of the groups and users that you had previously added. The SQL Security Manager will recognize that the users already exist in SQL Server and will not modify SQL Server but will go ahead and add the necessary security entries in Windows NT.

Note If you reinstalled Windows NT because you were changing the domain for an Advanced Server, you will need to delete and re-add the users in SQL Server because the default domain name has changed and will cause the user name mapping to fail.


Network Protocol Issues

SQL Executive requires a Net-Library that allows a trusted connection. The only Net-Libraries that support a trusted connection are named pipes and multiprotocol.

Additionally, if you have ever had a parallel installation of SQL Server with both version 4.21 and version 6.0 running on the same machine and SQL Server version 6.0 or version 6.5 is set up to listen on an alternate named pipe, you must change the registry entry for the ServerHost value for SQL Executive so it connects to the correct pipe.

Caution Incorrect changes or deletions made to the Registry can damage Windows NT and prevent the system from running normally.

Changes to the ServerHost value in the Registry can be found in:

HKEY_LOCAL_MACHINE on Local Machine
   \SOFTWARE
      \MICROSOFT
        \MSSQLServer
           \SQL Executive
              \ServerHost

For example, if you have set up SQL Server 6.5 to listen on \\.\Pipe\Mssql\Query, you would enter this for the ServerHost value. Stop and restart SQL Server for the changes, particularly the network protocol, to take effect.

If SQL Server is set up to listen on multiprotocol and not on named pipes, the SQL client configuration utility must also have multiprotocol as the default Net-Library. In addition, the Advanced tab of the SQL Client Configuration Utility must include the Windows NT computer name in the Server box and MultiProtocol in the DLL Name box. Click Add/Modify to add this advanced configuration if it is not already present. You must also add the server name to the ServerHost key in the Registry as listed above.


Test Task

For testing purposes, it is often helpful to attempt a simple task separate from other tasks you have created. The following task may be useful in debugging SQL Executive issues:

On the Server menu in SQL Enterprise Manager, click Scheduled Tasks.

Click New Task and create a new task with the following attributes:

Name: Testdump

Type: TSQL

Database: Pubs

Command: dump database pubs to diskdump

Schedule: On demand

Click Add.

Note You must execute this task from the msdb database.

Click Testdump and then click Run Task.

Click Task History to see if the task was successful. You may need to click Refresh once or twice to get the display to update properly.

You may also want to try this statement in ISQL/w to verify that you have entered it correctly and that it works as expected:

sp_runtask Testdump

This statement takes a maximum of 4 seconds to execute, so the response between start and completion, that is, success or failure, will be obvious within a few seconds. Again, you may need to click Refresh in the Task History box once or twice to update the display.


Debugging SQL Executive

In SQL Server 6.5, you can view the SQL Executive Error Log. Do the following to set up an error log for SQL Executive.

To configure the server

In the Server Manager window of SQL Enterprise Manager, select the server for which you want to set configuration parameters.

Right-click the server's SQL Executive icon. Click Configure on the shortcut menu.

Set a parameter for the Error Log File. Specify the path and file name that error information for SQL Executive will be written to.

An error log adds substantial process overhead. Use the error log only when directed to do so by your primary support provider or when you are attempting to troubleshoot a specific SQL Executive problem.

A registry key can be added to the Registry to assist with troubleshooting when all other methods fail.

To modify the Registry

Execute Regedt32.exe and go to:

HKEY_LOCAL_MACHINE on Local Machine

\SOFTWARE

\MICROSOFT

\MSSQLServer

\SQL Executive

On the Edit menu, click Add Value.

Add a value named VerboseFile with a data type of reg_sz.

In the String box, type a full path and file name for a file that will hold the results of the output from SQL Executive. For example, type:

c:\mssql\log\sqlexec.log

Stop and restart SQL Executive. Now test the tasks or alerts that you want to run, and view the output in the file that you added to the Registry.

The following method can also get verbose output from SQL Executive.

A quick way to see what is actually happening is to use the debugging switches -c and -v.

To monitor SQL Executive

Stop SQL Executive.

From a command prompt, change the directory to \Mssql\Binn.

Type the statement:

SQLEXEC -c -v

Note This statement is case-sensitive; you should enter the switches in lowercase only.

Alternatively, you can redirect output to a file by using the following:

SQLEXEC -c -v > sqlexec.out

When the service is started this way, nothing will be echoed to the screen. Wait for approximately 1 to 2 minutes for the service to start, press CTRL+C and then press y to stop the service.

You will not see your commands echoed to the screen. Once the service is stopped, you can edit the Sqlexec.out file and see the output generated by the debugging switches.

These items should solve the vast majority of causes for SQL Executive failure. If, after doing all of the above, SQL Executive still does not start, contact your primary support provider for more assistance.


Deadlocking with Distributed Transactions

Implementing distributed transactions is easy with MS DTC and SQL Server.

In distributed transactions, deadlocks can occur. This section explains options that are available for application developers planning to implement distributed transactions with SQL Server 6.5.

SQL Server 6.5 includes the Microsoft Distributed Transaction Coordinator (MS DTC), which provides robust, high-performance, scalable, easy-to-use distributed transaction capability for the Microsoft Windows NT and Windows 95 operating systems. MS DTC addresses the challenges of processing transactions over a distributed set of software components that exist on a single computer or on a system of networked computers. MS DTC is fully integrated with Microsoft SQL Server. Through MS DTC, remote stored procedure calls can participate in distributed transactions, so that changes on multiple servers can be committed as a single unit of work.

MS DTC includes no facilities for deadlock avoidance or detection. Application developers who plan on implementing distributed transactions with MS DTC and SQL Server have two options:

  • Implement deadlock avoidance in the application by serializing the transactions' access to common tables among different servers.
  • Implement time-outs either within the application or by using a SQL Server server-wide trace flag.

If the application has tight control over what distributed transactions are performed, it can serialize access to common resources in such a way that any deadlocks that may occur would be contained within a single SQL Server where they could be detected and dealt with like normal deadlocks are detected and dealt with. For instance, if the intention is to maintain transactional integrity among three tables on three different SQL Servers (T1 on Server1, T2 on Server2, and T3 on Server3), you should always issue the table modification queries in the same table order for any distributed transaction that affects these tables. This may, for example, always be T1 first, T2 second, and T3 third.

Another option that you can use when there is little control over the types of distributed transactions that might be issued is time-outs. For DB-Library and ODBC applications, this can be implemented in the calling program. For ad hoc Transact-SQL usage, SQL Server 6.5 has implemented trace flag 8503, which allows a system administrator to define a server-wide MS DTC transaction time-out value for server-to-server MS DTC transactions started with either BEGIN DISTRIBUTED TRAN or through the implicit transaction mechanisms, REMOTE PROC TRANS or SET REMOTE_PROC_TRANSACTIONS ON. When the trace flag is set, the sp_configure remote query time-out value is used as the transaction time-out value, in seconds. If the transaction is still active after the time has elapsed, the MS DTC initiates transaction abort by using the Abort transaction method. A value of 0 represents an infinite time-out.


Orphaned Connections

When orphaned processes occur, here's how to troubleshoot the problem.

When a SQL Server client disconnects from a SQL Server, the connection process should be cleared up on the server side. If the connection processes are not cleared up, they become orphaned or ghost processes that use up valuable resources like locks and user connections. The orphaned processes are typically caused by improper closing of client applications and network-related problems, and the remedies usually require troubleshooting client applications and fine-tuning network configurations.

When you troubleshoot this problem, keep the following in mind:

  • SQL Server does not and should not proactively probe the client connection to determine its current status.

    The lower-level IPCs such as named pipes, SPX/IPX, or TCP/IP sockets are responsible for managing the client connections.

  • An IPC typically has its own mechanism to manage the client connections.

    When client connections are nonresponsive for a certain amount of time, the Windows NT Server typically will either detect this by sending the "keep alive" probes or clear the connection after it idles for a configured amount of time.

  • Under certain situations, such as client GP-fault or hang, the client may still respond to server probes even if the application is already dead.

    In this case, the Windows NT Server may keep this client connection indefinitely, as long as the client is not shut down.

  • If a Windows NT Server does not terminate a dead connection, SQL Server assumes the connection is still active and does not clear it up.
  • If the Windows NT Server has successfully terminated the connection but the client connection still exists on the SQL Server (indicated by sp_who), there may be a problem with SQL Server's connection management.

    Contact your primary support provider to resolve this issue.

If you suspect orphaned processes exist on your SQL Server, the following are steps you can take to troubleshoot the problem:

Identify the orphaned processes using sp_who.

This will indicate the applications that were associated with these processes.

After you identify the orphaned processes, you can choose to either ignore them (if they are not holding any locks or using many connections) or kill them using the SQL Server KILL statement.

Check with application users to ascertain if they have closed applications incorrectly; correct any improper procedures.

An example of incorrectly closing an application is doing a warm or cold reboot of a workstation without first exiting all applications.

Check the history of the workstation and correct stability problems.

Some examples of an unstable workstation are hangs and GP-faults.

Check whether the IPC session is still active on the Windows NT Server where SQL Server is running.

Depending on which IPC you use, the commands for using it are different. For example, if you are using named pipes, the command is NET SESSION or NET FILES. If you are using TCP/IP sockets, you can use NETSTAT to display active TCP sessions. If you are using SPX/IPX, you may have to use Performance Monitor to monitor the open connections for NWLink SPX.

  • named pipes: Windows NT Server depends on clients to initiate "keep alive" traffic. If the client stops sending "keep alive" packets, Windows NT Server clears the client session after waiting for a configured amount of idle time. The idle time is configured in the autodisconnect parameter of the Windows NT Registry:

HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\LanmanServer

\Parameters

  • TCP/IP sockets: Windows NT Server periodically sends "keep alive" packets to clients, and clients are expected to respond. If the client fails to respond to those packets, Windows NT clears the TCP session after trying for a configured number of times. The parameters involved are KeepaliveInterval and KeepaliveTime in the Windows NT Registry:

HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\Tcpip

\Parameters

  • SPX/IPX: Similar to its behavior with TCP/IP, Windows NT Server periodically sends "keep alive" packets and clients respond. Windows NT clears the SPX connections if no responses are received after the configured number of "keep alive" packets are sent. The parameters involved are KeepAliveCount and KeepAliveTime-out in the Windows NT Registry:

HKEY_LOCAL_MACHINE

\SYSTEM

\CurrentControlSet

\Services

\NWLnkSPX

\Parameters

Note If the "keep alive" parameters for your IPCs are configured to never time out, Windows NT keeps the IPC sessions indefinitely, even if the clients are completely shut down. In this case, SQL Server also keeps these client processes indefinitely.

For more information about the parameters, see your Windows NT documentation or your Windows NT Resource Kit. If you suspect your Windows NT Server does not clear those sessions according to your configuration parameters, contact your primary support provider.

If the IPC session no longer exists on the Windows NT Server but SQL Server still keeps client processes (shown by sp_who), you can use the KILL statement to clear the process as a temporary solution, and then contact your primary support provider for further assistance.


Tracing SQL Generated by the Microsoft SQL Server ODBC Driver

The ODBCSpy utility provides complete trace information about all the ODBC calls made to a specific ODBC data source.

Tracing the SQL statements generated by a two-tier ODBC driver can sometimes help you determine if a problem lies in the ODBC SQL statements generated by the ODBC application or in the native SQL generated by the driver to implement the application's ODBC SQL statements.

The ODBC software developer's kit (SDK) provides two tools for monitoring the ODBC commands coming from applications. The first tool is the trace utility of the ODBC Driver Manager, which is started from the ODBC Administrator. You can click Options in the ODBC Administrator window, then select the trace options to start tracing all calls made to any ODBC data source on the client. This traces ODBC calls right after they come into the driver manager and is helpful in debugging problems that the driver manager may have when connecting to a driver. This is a fairly minimal trace, however, and the second tool, ODBCSpy, is the one most commonly used to troubleshoot ODBC calls.

The ODBCSpy utility ships with the ODBC SDK and can be used to get a thoroughly informative trace of all the ODBC calls made to a specific ODBC data source. ODBCSpy traces calls as they are passed from the driver manager to the ODBC driver. It shows all of the parameters passed for each call to the driver and the information returned from the driver. If an error is encountered, ODBCSpy calls SQLError for all error messages returned and logs the full information about the errors in trace.

There are also third-party ODBC packages that provide ODBC tracing tools.

ODBCSpy can tell you what commands are going into an ODBC driver, but they must rely on the native tracing functions of the data source to determine what SQL statements are generated by two-tier ODBC drivers such as the Microsoft SQL Server ODBC driver. All versions of Microsoft SQL Server provide trace flags to trace all the SQL statements coming into the server.

The 4032 trace flag traces the SQL statements coming in from the client. This trace can be returned to the client by also using the 3604 trace flag or the SQL statements can be logged in SQL Server's error log by using the 3605 trace flag. The "-1" trace flag will make the trace cover all clients connecting to the server; otherwise, the trace is specific to the connection issuing the trace command. The statement to turn on the trace flags is:

DBCC TRACEON(flag1,flag2,…,flagn)

For example:

Log all SQL statements from all clients to the error log:

DBCC TRACEON(4032,3605,-1)

Echo all SQL statements from this connection back to the client:

DBCC TRACEON(4032,3604)

The traces remain on until turned off with DBCC TRACEOFF or until the SQL Server is stopped and restarted. The trace flags can also be turned on if SQL Server is started from the command prompt.

The SQL Server 6.5 error log is in C:\Mssql\Log. For ODBC clients, it is usually best to log the SQL statements to the error log using the 3605 trace. If troubleshooting is being done through ODBCTest, then it is fairly easy to issue:

SQLExecDirect(hstmt,"dbcc traceon(3605,4032)",SQL_NTS);

This can also be added to an application that calls the ODBC API directly and that is being interactively debugged. If the ODBC application opens multiple connections or does not offer the ability to call the ODBC API directly, it is best to isolate the application so that it is the only application running against a SQL Server.

Then, from either ODBCTest, the SQL Server ISQL/w utility, or any other utility that will allow the entry of ad hoc commands, issue:

dbcc traceon (4032,3605, -1)

To read the SQL Server error log, it is recommended that you use Write.

The SQL statements generated by Microsoft SQL Server ODBC driver are sent to the server in one of two ways, either as standard SQL statements or as SQL Server remote procedure calls (RPCs).

SQL Server 6.5 introduced the SQL Trace utility. Users can use SQL Trace filters instead of the DBCC trace flags to view the SQL statements sent to SQL Server. For information about how to turn on filters to capture SQL statements, see What's New in SQL Server 6.5. Once a filter has been applied to an ODBC client, the SQL commands being sent to the server by the driver will be visible. For example, when executing this standard SQL statement:

SQLExecDirect(hstmt,
              "exec parmproc @cntr=1, @string='abcde'",
              SQL_NTS);

This SQL Trace format returns:

-- 4/16/96 20:24:17.783 SQL (ID=7, SPID=13, User=sa(REDMOND\alanbr),
   App='Microsoft ODBC SDK v2.0', Host='ALANBR3'(bf) )
exec parmproc @cntr = 1, @string = 'abcde'
go

When executing the same procedure with a remote procedure call:

SQLExecDirect(hstmt,
              "{ call parmproc (1,'abcde') }",
              SQL_NTS);

This SQL Trace format returns:

-- 4/16/96 20:24:41.116 RPC (ID=7, SPID=13, User=sa(REDMOND\alanbr)<
   App='Microsoft ODBC SDK v2.0', Host='ALANBR3'(bf) )
parmproc 1, "abcde", 1, "abcde",
go


Understanding and Resolving SQL Server Blocking

Understanding and Resolving
SQL Server Blocking

Blocking is easy to prevent with Microsoft SQL Server.

Microsoft SQL Server is a transaction-oriented relational database management system (RDBMS) that is often used in highly concurrent environments with many simultaneous users. It maintains transactional integrity and database consistency by using locks (for INSERTs) at the table, page, and, in version 6.5, at the row level.

An unavoidable characteristic of any lock-based concurrent system is that under some conditions blocking can occur. Blocking is when one connection holds a lock, and a second connection wants a conflicting lock type on the same data, which forces the second connection to wait, or block, on the first. This article discusses why this happens and provides techniques for understanding, resolving, and preventing blocking problems.

In this discussion, the term "connection" refers to a single logged-in session on the database. Each connection appears as a server process ID (SPID). Each of these are often referred to as a "process," although it's not a separate process context in the normal sense. Rather, each SPID consists of the server-side resources and data structures necessary to service the requests of a single connection from a given client. A single client application can have one or more connections. From the perspective of SQL Server, there's no difference between multiple connections from a single client application on a single client computer, versus multiple connections from multiple client applications on multiple client computers. One connection can block another connection regardless of whether they emanate from the same application or from separate applications on two different client computers.


Overview

To achieve consistent results during concurrent update activity, any database must impose isolation between transactions. Without isolation, inconsistent results may be seen under concurrent use. Most database products use locks to impose isolation. There are other isolation techniques besides locks, such as versioning (also called time-domain addressing), but each technique has its own cost and overhead. For details see Transaction Processing: Concepts and Techniques, by Jim Gray and Andreas Reuter, ISBN 1-55860-190-2.

Locking, as a means of implementing isolation, is well understood and highly refined in current products. All parts of the transaction must be protected with locks, or else ROLLBACK would not be reliable. Some of the actions needing locking protection may not be obvious. These include locks on system catalog tables, indexes, and allocation structures such as extents.

Locks are automatically acquired by the database server in response to certain types of queries. Locks are not typically acquired under manual programmatic control, although the current product allows this by using optimizer hints.

Locks are not generally intended for use under manual control to implement pessimistic concurrency. For example, one connection should not manually acquire a lock to indicate to other connections the page or row is "in use." Rather, the application should use an "in use" column as a flag to other connections. Alternatively, the application can use a cursor under optimistic concurrency control, which would then signal the application if another connection changed the data during the interval the first connection was browsing the data. For details on implementing cursors, see SQL Server Books Online and Knowledge Base article Q156489, "Overview of SQL Server, ODBC, and DB Library Cursors."

For the best scalability, performance, and concurrency, application and query design should emphasize keeping transaction path length short and holding locks as briefly as possible. The foundation of most concurrency problems is laid when the application and database are designed. For this reason it's critical that these issues be well understood at design time. Otherwise, a hidden performance limitation can be unintentionally engineered into the application, and this may not appear until full-scale stress testing. Stress testing should always be done at the projected full user load to ensure that concurrency at this load factor meets your requirements. Failure to do stress testing may result in concurrency, blocking, and performance problems appearing late in the design cycle or (still worse) after application deployment. Problems discovered at this stage can be very costly to correct.

Different RDBMSs handle locking and concurrency differently. If the application is being ported from one RDBMS to another, you cannot expect the two databases to behave identically. The application may require adjustments, especially if the application takes advantage of a feature or characteristic unique to one RDBMS. This is so even if the application uses only standard ANSI SQL, since locking and concurrency control issues are implementation specific.

The RDBMS designers must balance a tradeoff between locking granularity and overhead. Fine-grain locks at the row or column level can allow more concurrency but also entail greater overhead. This relationship between locking granularity and overhead has been well understood for many years in the academic community (see "Effects of Locking Granularity in a Database Management System," September 1977, and "Locking Granularity Revisited" June 1979, by Daniel Ries and Michael Stonebraker from ACM Transactions on Database Systems). SQL Server locks at the table, page, or (in version 6.5) row level for INSERTs. Future versions of SQL Server will have more extensive row-level locking, but this will not prevent blocking problems.

No matter how fine-grained the locks taken, if the application doesn't exercise good discipline regarding transaction path length and query management, blocking problems can develop. This is analogous to a slow moving automobile causing a backup by driving in the left lane of a freeway. The driver may think that sufficient lanes should be made available for him to drive any way he wishes. However no feasible number of highway lanes will allow drivers to disregard good lane discipline without causing traffic to slow down. Likewise, no RDBMS isolation technique can allow applications to disregard the impact they have on concurrency and scalability.


Investigating a Blocking Problem

Identify the SPID at the head of the blocking chain. Most blocking problems happen because a single process holds locks for an extended period of time. This usually causes a chain of blocked processes, similar to a slow moving automobile causing a backup on the freeway. Identify the head of the blocking chain from SQL Enterprise Manager by clicking CurrentActivity on the Server menu and observing the Object Locks tab. Alternatively you can use the following example query, which should return one row for each SPID at the head of a blocking chain. See also Knowledge Base article Q122485, "Identifying SPID Responsible for Lock Chain."

create procedure sp_blocker

as

declare @statement char(255)

if exists (select * from sysprocesses where spid in (select blocked from sysprocesses))

select spid,status,loginame=substring(suser_name(suid),1,12),

hostname=substring(hostname, 1, 12), blk=convert(char(3),blocked),

dbname=substring(db_name(dbid),1,10),cmd, waittype

from sysprocesses

where spid in (select blocked from sysprocesses)

and blocked = 0

else

select "No blocking SPIDs found!"

Find what query the blocking SPID is running by running DBCC INPUTBUFFER (spid), where spid is the blocking SPID. Alternatively you can use SQL Enterprise Manager by clicking Current Activity on the Server menu and double-clicking on the SPID to show the input buffer. Save this information.

Find the type of locks the blocking SPID is holding by running sp_lock, or querying master..syslocks. Save this information. Below is an example query. Alternatively you can use SQL Enterprise Manager.

select spid, syslocks.type, locktype=name, table_id=id, page

from syslocks, master.dbo.spt_values v

where syslocks.type=v.number

and v.type='L'

and (syslocks.type & 256)=256

and spid=<blocking spid number>

Sometimes it's necessary to use queries instead of SQL Enterprise Manager because some types of tempdb blocking problems can prevent running queries that use temp table operations. Using direct queries gives the control necessary to avoid this. An example of a query that results in temp table operations is sp_lock, which does an ORDER BY.

Find the transaction nesting level and process status of the blocking SPID. Save this information. This is essentially the same number as @@TRANCOUNT, but can be determined from outside the SPID by using the command DBCC PSS. Example syntax:

dbcc traceon(3604) /* return subsequent DBCC output to client rather than errorlog */

go

SELECT SUID FROM SYSPROCESSES WHERE SPID=<blocking SPID number>

go

DBCC PSS (suid, spid, 0) /* where suid is from above, and spid is the blocking spid number */

go

Note The DBCC PSS statement and the format of the PSS structure are undocumented and unsupported. Their discussion in this article is solely intended to aid customers in diagnosing specific types of blocking problems in their existing systems. The DBCC PSS command should not be incorporated in any existing applications. Microsoft may either discontinue or alter the DBCC PSS command and the PSS structure in future versions of SQL Server.

In the returned information, note pxcb->xcb_xactcnt=n, where n is the @@TRANCOUNT value for the SPID. This shows the transaction nesting level for the blocking SPID, which in turn can explain why it is holding locks. For example, if the value is > 0, then the SPID is in the midst of a transaction, in which case it's normal that it retain any exclusive locks acquired. Note also pstat=n, where n indicates the internal status of the SPID. This can indicate why the blocking SPID may itself be waiting for certain events.

You can also determine whether any long-term open transaction exists in the database by using DBCC OPENTRAN(database_name).

By examining the above four pieces of information, you can usually determine the cause of most blocking problems. Following is a discussion of how to use this information to identify and resolve some common blocking scenarios. See also Knowledge Base article Q125770 "Locking Behavior of Updates and Deletes in SQL Server."


Identifying and Resolving Common Blocking Scenarios

Blocking caused by normally running query with long execution time.

A long-running query can block other queries. For example, a bulk DELETE or UPDATE can acquire many locks, which (whether they escalate to a table lock or not) block other queries. For this reason, you generally don't want to intermix long-running decision support queries and OLTP queries on the same database. You can identify this situation by observing the blocking SPID. The INPUTBUFFER may point to a query known to have a long execution time. This often causes a steady I/O consumption, visible by running the following query several times in succession:

SELECT SPID, PHYSICAL_IO FROM MASTER..SYSPROCESSES

The PHYSICAL_IO value does not always reflect all the work done by a SPID because work done on its behalf by other processes (such as the read-ahead manager) is not charged back to the SPID. However, it's often an approximate indication of I/O activity. If it continuously increases, inspect the query running and determine whether it should be running at the time. Run it in isolation on a quiescent computer, and monitor the I/O activity with SET STATISTICS IO ON. If the query consumes a high amount of I/O resources, it may cause blocking when run on a busy system. The solution is to look for ways to optimize the query by changing indexes, breaking a large complex query into simpler queries, or running the query during off hours or on a separate computer.

This class of blocking problem may just be a performance problem and may need pursuing as such. For more information, see Knowledge Base article Q110352, "Optimizing Microsoft SQL Server Performance." One reason queries can be long running and cause blocking is inappropriate use of cursors. Cursors can be a convenient method for navigating through a result set but they may be slower than set-oriented queries. For more information, see Microsoft SQL Server 6.5 Unleashed, by David Solomon, Ray Rankins, et al, ISBN 0-672-30956-4.

Blocking caused by sleeping SPID that has lost track of transaction nesting level.

This can often be identified by a SPID that is sleeping, awaiting command, yet whose @@TRANCOUNT is > 0. This can happen if the application issues the DB-Library call dbcancel() or the ODBC call sqlcancel(), without also issuing the required number of ROLLBACK/COMMIT statements. Issuing these calls cancels the query and the batch but does not automatically rollback or commit the transaction. This can be seen by issuing a simple query from ISQL/w, such as BEGIN TRAN SELECT * FROM MASTER..SYSMESSAGES, and clicking Cancel. After the query is canceled, SELECT @@TRANCOUNT indicates the transaction nesting level is 1. Had this been a DELETE or UPDATE query or had HOLDLOCK been used on the SELECT, all the locks acquired would still be held. Applications must properly manage transaction nesting levels or else they can cause blocking following query cancellation. For more information, see Knowledge Base article Q117143 "When and How to Use dbcancel() or sqlcancel()." The transaction nesting level of the SPID can be observed by using DBCC PSS.

Blocking caused by sleeping SPID whose corresponding client application did not fetch all result rows to completion.

This is just plain bad application design. After sending a query to the server, all applications must immediately fetch all result rows to completion. If the application does not fetch all result rows, locks can be left on the tables, which can block other users. If you're using an application that transparently submits SQL statements to the server, the application must fetch all result rows. If it does not (and if it cannot be configured to do so), the blocking problem may not be resolvable. A possible solution is restricting such applications to a reporting or decision-support database. This problem can often be identified by the blocking SPID being in a sleeping or awaiting-command state, with a transaction nesting level of 0. If you cannot examine @@TRANCOUNT within the application, it's possible to examine it externally by using DBCC PSS. Sometimes the SPID will have a waittype of 0x800 because after the client application quits fetching result rows, the server will try to write a buffer to the client and wait on the client to pull data from its end.

Blocking caused by distributed client/server deadlock.

Unlike a conventional deadlock, which is detectable by using the RDBMS lock manager, a distributed deadlock is not detectable. The blocking SPID often appears sleeping with a waittype of 0x800 (waiting on a network I/0). You cannot use the KILL statement on a SPID in this state because it is waiting on a return from a Windows NT API call. A distributed client/server deadlock can happen if the application opens more than one connection to the RDBMS and submits a query asynchronously. Below are two examples of how this can happen and possible ways the application can avoid this.

  • Client/server distributed deadlock with single-client thread. If the client has multiple open connections (dbprocs in DB-Library terms) and a single thread of execution, distributed deadlock can occur. For brevity, we use the term dbproc to refer to the client connection structure. In ODBC API terms, the closest analog is an hdbc.

    In the preceding case, a single client application thread has two open connections. It asynchronously submits an SQL operation on dbproc1. This means it doesn't wait on the call to return before proceeding. The DB-Library asynchronous call is dbsqlsend(). ODBC applications select asynchronous mode with SQLSetStmtOption() and by using the SQL_ASYNC_ENABLE parameter. The application then submits a SQL operation on dbproc2, and awaits results to start processing the returned data. When data starts coming back (from whichever dbproc first responds), it processes to completion all the data returned on that dbproc. Let's say this is dbproc1. It fetches results from dbproc1, until spid1 gets blocked on a lock held by spid2 (since the two queries are running asynchronously on the server). At this point, dbproc1 will wait indefinitely for more data. Spid2 is not blocked on a lock and tries to send data to it's client, dbproc2. However, dbproc2 is effectively blocked on dbproc1, awaiting the single thread of execution to run.

  • Client/server distributed deadlock with thread per connection. Even if a separate thread exists for each connection on the client, a variation of distributed deadlock can still happen. This is similar to the first case except dbproc2/spid2 is running a SELECT with the intention of performing row-at-a-time processing and handing each row, by using a buffer, to dbproc1 for inserting in the same table. Eventually, spid1 becomes blocked on a lock held by spid2. Spid2 then writes a result row to the client dbproc2. Dbproc2 then tries to pass the row in a buffer to dbproc1 but finds that dbproc1 hasn't yet fetched the last row from the buffer (since it's blocked waiting on spid1, which is blocked on spid2).

    Both cases are fundamental issues that application developers must be aware of and write code for handling. There are two reliable solutions: use a query time-out or bound connections.

  • Query time-out. By supplying a query time-out, distributed deadlocks are broken when the time-out happens. For more information about using a query time-out, see the DB-Library or ODBC documentation.
  • Bound connections. This feature allows a client having multiple connections to bind the connections into a single transaction space so they don't block each other. For more information, see "Bound Connections" in SQL Server Books Online.

Blocking caused by SPID that is in "golden" or rollback state.

A data modification query that is killed or canceled outside of a user-defined transaction will be rolled back. This can also occur as a side effect of the client rebooting and its network session disconnecting. Likewise, a query selected as the deadlock victim will be rolled back. A data modification query often cannot be rolled back any faster than the changes were initially applied. In the case of a DELETE, INSERT, or UPDATE that has been running for an hour, it could take at least an hour to roll back. If the server is shut down in the midst of this and then restarted, the database will be in recovery mode and inaccessible until all open transactions are processed. Startup recovery takes essentially the same time per transaction as run-time recovery; plus, the database will be inaccessible during this period. Hence, forcing the server down to fix a SPID in a rollback state will often be counterproductive. This is expected behavior since the changes made must be completely rolled back or else transactional and physical integrity in the database is compromised. Since this must happen, SQL Server will mark the SPID in a "golden" or rollback state, which means it cannot be killed or selected as a deadlock victim. This can often be identified by observing the sp_who output, which may indicate the command of ROLLBACK. However, the most reliable way is to inspect the DBCC PSS of the blocking SPID in question and observe the pstat value. For example, the pstat value might be:

pstat=0x4000, 0x800, 0x100, 0x1

The meaning of these bits is:

0x4000 -- Delay KILL and ATTENTION signals if inside a critical section

0x2000 -- Process is being killed

x800 -- Process is in backout, thus cannot be chosen as deadlock victim

x100 -- We're in the middle of a single statement xact

0x1 -- Process has received an ATTENTION signal

The above would be a typical situation if a long-running data modification was canceled and the SPID was found to block users, yet be unkillable. This situation is normal; the transaction must be backed out. It can be identified by the above bits.

In addition to the pstat field of the PSS, the sysprocesses.waittype field can also give information about why the SPID may be waiting. Below are some common values:

0x800 -- waiting on network I/O completion

0x8011 -- waiting on buffer resource lock(shared) request

0x81 -- waiting on writelog

0x0020 -- waiting on buffer in I/O

0x0005 -- waiting on exclusive page lock

0x13 -- waiting on buffer resource lock(exclusive) request

0x8001 -- waiting on exclusive table lock

0x8007 -- waiting on update page lock

0x8005 -- waiting on exclusive page lock

0x6 -- waiting on shared page lock

0x8006 -- waiting on shared page lock

0x23 -- waiting on buffer being dumped

0x5 -- waiting on exclusive page lock

0x0013 -- waiting on buffer resource lock(exclusive) request

0x0022 -- waiting on buffer being dirtied

Blocking caused by version 6.5 atomic SELECT INTO behavior.

By definition, SQL Server treats each statement as a separate transaction. Beginning with SQL Server 6.5, SELECT INTO was made consistent with this standard by including the table creation and data insert phases in a single atomic operation. A side effect of this is that locks on system catalog tables are maintained for the duration of a SELECT INTO statement. This is more frequently seen in tempdb, since applications often select into temporary tables. Blocking caused by this can be identified by examining the locks held by the blocking SPID. The atomic SELECT INTO behavior can be disabled with trace flag 5302. For more information, see Knowledge Base article Q153441, "SELECT INTO Locking Behavior."

Blocking caused by an orphaned connection.

If the client application traps or the client workstation is rebooted, under some conditions the network session to the server is not immediately canceled. From the server's perspective, the client appears to be present, and any locks acquired can still be retained. See Knowledge Base article Q137983, "How to Troubleshoot Orphaned Connections in SQL Server."


Application Involvement in Blocking Problems

SQL Server is essentially a puppet of the client application. The client application has almost total control over (and responsibility for) the locks acquired on the server. While the SQL Server lock manager automatically uses locks to protect transactions, this is directly instigated by the query type sent from the client application and how the results are processed. Therefore, resolution of most blocking problems necessitates inspecting the client application.

Often, turnkey client applications and higher-level application development tools are used against SQL Server. These may encapsulate the DB-Library or ODBC API calls to the database in a higher abstraction level; however, from the perspective of SQL Server, there's essentially no difference between one of these higher level applications, a call-level DB-Library application, or a call-level ODBC application. SQL Server only perceives a stream of Transact-SQL statements and certain control tokens sent by each client API call. The same basic issues cause blocking problems whether the client application is a call-level application written in C or a higher-level application that encapsulates database calls. Likewise, the solution to these problems is generally the same.

This means that no matter what level of visibility the application exposes regarding the database calls being made, a blocking problem will nonetheless frequently require inspection of the exact SQL statements submitted by the application and what the application's exact behavior is regarding query cancellation, connection management, fetching all result rows, and so on. If the development tool does not allow explicit control over connection management, query cancellation, query time-out, result fetching, and so on, blocking problems may not be resolvable. This potential should be closely examined before selecting an application development tool for SQL Server, especially for business-critical OLTP environments.

There may be a tendency to focus on server-side tuning and platform issues when facing a blocking problem. This will usually not lead to resolution and can absorb time and energy better directed at examining the client application and the queries it submits.

Several tracing facilities may be used to examine what the client application is sending to the server. Each client application may have it's own tracing feature, so examine the documentation for the application. In addition, server-side tracing can be done using the -T4032 trace flag and the SQL Trace facility. Usually you can resolve a blocking problem without using these, but they are available if needed.


Application Design Techniques to Avoid a Blocking Problem

Never do | Always do
Fail to immediately fetch all result rows to completion. | Allow for query cancellation by using dbcancel, sqlcancel, or an equivalent.
Design a large scale OLTP system using an application development tool that doesn't allow explicit control over connections, transactions, and the SQL syntax sent to the server. | Use a query time-out by using dbsetltime or SQLSetStmtOption to prevent a runaway query and avoid distributed deadlocks.
Use or design a client application that allows users to fill in edit boxes that generate a long-running query. Such an application may prompt you for inputs but allow you to leave certain fields blank or enter a wildcard for those blanks. This, in turn, can cause the application to submit a query with an excessive running time, causing blocking. | Immediately fetch all result rows to completion.
Use or design an application that allows for user input within a transaction. | Keep transactions as short as possible.
 | Explicitly control connection management.
 | Stress test application at full projected concurrent-user load.

It's vital that great care be exercised during the design and construction phase of the database and application. In particular, the resource consumption, isolation level, and transaction path length should be evaluated for each query. Each query and transaction should be as lightweight as possible. Good connection management discipline must be exercised. If this is not done, it's possible the application may appear to have acceptable performance at low numbers of users, but the performance could degrade badly as the users scale upward.

With proper application and query design, Microsoft SQL Server is capable of supporting many thousands of simultaneous users on a single server, with little blocking. The successful sites that reach this level typically use the techniques mentioned in this article.


Part 5 - Integrating with BackOffice

You can combine Microsoft products to provide convenient and efficient solutions for your enterprise. The articles in Part 5 discuss the integration capabilities of Microsoft SQL Server:

  • Thread Scheduling on Windows NT Server
  • Microsoft Exchange Server
  • Microsoft Systems Management Server


Thread Scheduling on Windows NT Server

Many of the performance and reliability gains of Microsoft SQL Server are achieved through close integration with Microsoft Windows NT Server.

Microsoft SQL Server is a Win32 application that runs on the Windows NT Server or Windows NT Advanced Server (NTAS) operating systems. In rare situations when SQL Server is running a compute-bound operation, the interactive console responsiveness of Windows NT may be diminished. This article discusses characteristics of the Windows NT process scheduler (often called thread scheduler or thread dispatcher) that relate to this behavior.

Windows NT Server and NTAS use the same system of scheduling Win32 processes and threads. With Windows NT, the unit of scheduling is the thread—hence, the term thread scheduling or dispatching is sometimes used. In other operating systems, this is usually called process scheduling. However, the term "process" will be used in this discussion, where appropriate. The unit of scheduling time is called the time slice or quantum.


Thread Priorities

Windows NT uses 32 numerical thread priorities, ranging from 1 (the lowest) to 31 (the highest) with 0 being reserved for system use.

Threads 1 through 15 are variable priority in that the scheduler adjusts the priority based on thread behavior. The base priority of a thread is the base level from which these upward adjustments are made. The current priority of a thread is called its dynamic priority. Interactive threads that yield before their time slice is up will tend to be adjusted upward in priority from their base priority. Compute-bound threads that do not yield, consuming their entire time slice, will tend to have their priority decreased, but not below the base level. This arrangement is often called heuristic scheduling. It provides better interactive performance and tends to lessen the system impact of "CPU hog" threads.

Windows NT also uses additional priority adjustments based on other events such as momentarily boosting thread priority when it returns from an I/O call, when returning from a user-mode subsystem call, and when receiving keyboard input.

Priority threads 16 through 31 are termed real time and do not vary in priority based on behavior. This provides more deterministic scheduling, which is useful for near-real-time systems.

Although there is a numerical priority for each thread, these are usually referred to within a Win32 program by their process priority flag or thread priority flag. There is a mapping of these flags to numerical thread priorities, which is detailed in the Win32 software developer's kit and Windows NT Resource Kit, Volume 3. In this article, threads are referred to by their numerical equivalent.


Thread Scheduling

The key to understanding Windows NT thread scheduling and resultant application behavior is knowing the central algorithm used. This algorithm is very simple and is the same one a number of other operating systems use: the highest priority ready thread gets run. A list of ready threads or processes exists, which is often called the dispatch queue or eligible queue. The queue entries are in order based on their individual priority. A hardware-driven real-time clock or interval timer will periodically interrupt, passing control to a device driver that calls the process or thread scheduler. The thread scheduler will take the highest priority entry from the queue and dispatch it to run.

Therefore, a hardware event drives the regular examination of thread states and the evaluation of which thread will run next. The frequency of this operation is quite rapid, often from 10 to 32 milliseconds on most systems.

Neither Windows NT nor many other operating systems use CPU quotas. The scheduling algorithm merely selects the highest priority ready-to-run thread and allows it to run uninterrupted until the next clock tick, at which time the scheduler gets control and reevaluates which thread has the highest priority and is ready to run. However, if the previously running thread still has the highest priority and is still ready to run—has not blocked on I/O or otherwise changed states—it will be run again.

Also, there is essentially no gradual or proportional control over the amount of CPU time a compute-bound thread receives. Often the misconception exists that by lowering the priority of a compute-bound thread by a certain amount, the CPU time will decrease proportionally. In actuality, it will receive just as much time as before because it has a higher priority than other threads. For example, a compute-bound thread could be diminished from priority 31 to 16, and as long as all other threads are at 15 or below, it will receive just as much time at 16 as at 31, and its system impact will be just as great.

The scheduler attempts to minimize this situation for threads in the variable class, which ranges from 1 to 15. However, highly compute-bound threads can still degrade overall system responsiveness in some circumstances. You can usually investigate these situations in the following way:

  • Use Performance Monitor to identify which threads are consuming CPU time.
  • Inspect the dynamic-thread priority of the compute-bound thread with respect to that of other slowly responding threads.

    You will usually see the compute-bound thread has an equal or higher priority than the others.

Schedulers of this type work remarkably well in a wide variety of situations, are well understood, and have low overhead. However, especially with compute-bound processes, they have limitations that are difficult to overcome. In these situations, the compute-bound process tends to get either all the available CPU time or little to none. It is very hard to throttle a compute-bound process so that it runs at a decent rate and yet does not dominate the system.


Controlling Thread Priority

An item that controls thread priority is the System application "tasking" option of the Windows NT 3.51 Control Panel. This allows you to control the degree of foreground priority boost that normal priority class applications receive. A foreground application is one that is made active by selecting it on the Windows NT desktop, therefore bringing it to the foreground. All other applications running are then termed background applications.

Note In Windows NT 4.0, you can change the performance boost in the Performance tab in the System Properties dialog box in Control Panel.


Windows NT 3.51 Options

  • Best Foreground Application Response Time, the default tasking option, increases in a foreground application's priority two levels.

    Neither foreground boost nor the heuristic priority adjustment will cause an application to change classes from normal to real time, or vice versa. The priority adjustment from these sources is bounded by the process class.

  • Foreground Application More Responsive than Background, the second tasking option, equates to a foreground boost of one level.
  • Foreground and Background Applications Equally Responsive, the third tasking option, deactivates any foreground boost. The SQL Server Setup program sets this during installation. This is mainly to prevent the database server from being CPU-starved by foreground applications and is the best setting for a dedicated SQL Server.


SQL Server Options

The SQL Server Setup program offers two options that affect the priority at which SQL Server runs (system behavior). These two options are listed under the Set server options portion of Setup and are called Dedicated multiprocessor performance and Boost SQL Server priority.

Dedicated Multiprocessor Performance

In SQL Server 6.x, the Dedicated multiprocessor performance Setup option has been replaced by the sp_configure advanced option called SMP CONCURRENCY. For more information about this option, see SQL Server 6.5 Books Online.

Selecting Dedicated multiprocessor performance on a symmetric multiprocessor (SMP) computer increases the scalability improvement that multiple CPUs have on SQL Server's performance. Selecting this option is not necessary for SQL Server to benefit from multiple CPUs, but it does increase the amount of improvement. A side effect of selecting the option is that it causes SQL Server to run at a priority of 15. This helps minimize scheduling overhead and obtain maximum benefit from SMP.

Boost SQL Server Priority

Selecting Boost SQL Server priority is possible on either a uniprocessor or SMP computer. When selected on a uniprocessor, SQL Server runs at priority 15, which is high but within the variable class of priorities that range from 1 through 15. When selected on an SMP computer, SQL Server runs at priority 24, which is midway into the real-time class of priorities that range from 16 through 31. The following table displays the priority at which SQL Server will run depending on the configuration.

Priority | Multiprocessor (MP) support | Boost | SMP computer
7 | N/A | OFF | No
15 | N/A | ON | No
7 | OFF | OFF | Yes
24 | OFF | ON | Yes
15 | ON | OFF | Yes
24 | ON | ON | Yes

With the previous in mind, a number of behaviors concerning SQL Server and the Windows NT thread scheduler are more understandable. One of these concerns when SQL Server is performing a CPU-intensive operation such as some types of joins. Depending on the exact operation and the amount of memory available, the operation could be done entirely in cache—effectively becoming CPU-bound. During this period, SQL Server (even when running at the default priority of 7) could degrade interactive performance. The conditions necessary for this behavior to occur do not happen often.

Another situation where this may occur is if a large single transaction or a large number of smaller transactions needed processing during start-up recovery, as would be the case if the server was abruptly shut down while these transactions were in progress. Depending on the amount of SQL Server cache buffer memory and the exact disk subsystem used, a lengthy recovery can take place mostly or entirely in cache. Because of this, it would be CPU-bound and could degrade interactive performance during this interval.

On a computer dedicated mainly as a database server, interactive console performance is usually not a priority. However, if necessary, SQL Server can be started from the command prompt in the IDLE priority class with a command such as:

start /low sqlservr -c -dc:\sql\data\master.dat

Another example is when SQL Server does a large disk initialization. In this case, the operation is extremely I/O-bound, and the lack of any scheduler I/O quotas causes behavior similar to a CPU-bound operation.

Using Boost SQL Server priority on an SMP computer dedicated to SQL Server can improve performance in limited situations. Boost SQL Server priority results in SQL Server running at priority 24, which is in the real-time class. Use of this option is not recommended outside of highly specialized conditions.

If the SQL Server computer is used for purposes other than a pure online transaction processing environment—for example, for ad hoc or decision support queries, as a file server or non-SQL application server, or for interactive use from the console—it is generally best to not use Boost SQL Server priority nor the SMP concurrency setting of -1. SQL Server version 6.0 will automatically use multiprocessor support on computers with three or more processors. Using either Boost priority, or SMP concurrency of anything other than 0 (autoconfigure) can significantly affect Windows NT console responsiveness and overall system behavior in a non-OLTP environment. The default settings for SQL Server version 6.5 provide the best overall behavior across the widest variety of circumstances and should be used in most cases.


Microsoft Exchange Server

Many corporate-solution providers combine Microsoft Exchange Server with Microsoft SQL Server.

To avoid any conflicts between Microsoft Exchange Server and Microsoft SQL Server, use the following basic troubleshooting techniques to diagnose and resolve most SQL Mail problems. Typically, errors in starting a SQL Mail session or sending mail from SQL Mail with a Microsoft Exchange Server fall into two categories: permissions problems and Microsoft Exchange client setup problems. SQL Mail functionality is documented in SQL Server 6.5 Books Online. You should thoroughly review this information before using SQL Mail.

To ensure that SQL Mail and Microsoft Exchange Server function together without conflict, perform the steps in the following checklist, preferably in the order given:

Log on to Windows NT with a user account that is an administrator of the local computer and is a domain account.

Confirm that the Microsoft Exchange client, Exchng32.exe, can connect to the Microsoft Exchange server and mail can be sent.

Confirm that the Microsoft Exchange profile used does not have a Personal Message Store (.pst) by running Mail and Fax in Control Panel.

Click Show Profiles.

In the Mail dialog box, click the default profile in the When starting Microsoft Exchange, use this profile list.

Click Properties.

Click the Services tab and confirm that the only services are Microsoft Exchange Server and Personal Address Book.

Click the Delivery tab. In the Deliver new mail to the following location list, click Mailbox - friendly_user_name where friendly_user_name is the name of the user who logged on to Windows NT in step 1.

To run SQL Mail with a Microsoft Exchange Server, the MSSQLServer service must be run under the same user account that logged on during step 1 above. To set this from Control Panel, double-click Services, click MSSQLServer, and then click Startup.

Confirm that the SQL Mail user name and password are correct by running SQL Server Setup. Click Set Server Options and then click Mail Login. The user name must match the profile name from step 3 above.

Note The password and Copy SQL Mail Configuration in the Current User Account check box do not matter since both no longer apply. SQL Server Setup version 6.5 will ask for only the Microsoft Exchange Profile name.

Test SQL Server access permissions to the Microsoft Exchange Server. You can do this by using the xp_cmdshell extended stored procedure, which runs with the same permissions as SQL Mail. Use the following command to test connectivity to the server, assuming the Microsoft Exchange Server is located on a computer named NTServer.

xp_cmdshell "NET USE \\NTServer\IPC$"

Note If the above command fails, step 4 has not been completed correctly.

At this point SQL Mail should be able to Autostart or be started manually with the xp_startmail extended stored procedure. Additionally, you can choose the profile to use with xp_startmail by replacing Profile name below with the profile name from step 3, as in the following example:

xp_startmail "Profile name",""


Microsoft Systems Management Server

Inventory information collected with Microsoft System Management Server can be stored in a Microsoft SQL Server database.

The System Management Server (SMS) provides a method for centrally managing software and hardware for corporate networks. It provides an integrated system to:

  • Maintain inventory of hardware, software, and configurations of computers
    in a network.
  • Distribute and install software.
  • Manage network applications.
  • Monitor network data flow. The SMS incorporates Microsoft SQL Server as a back-end database server. It uses SQL Server to store its inventory database.

SMS collects and maintains hardware and software inventory for an entire enterprise. This inventory information is stored in a SQL Server database, and there is one such inventory database per site.

  • The central site is the topmost site or is the root of the site hierarchy. An SMS system is composed of a central site that stores system-wide information and can have any number of sites beneath it. The central site requires a SQL Server database.
  • A primary site is any site that has its own site database. A site without a database is called a secondary site. A primary site can have one or more primary sites beneath it as well as one or more secondary sites beneath it.
  • A secondary site cannot store its inventory information. A secondary site forwards all its inventory and status information to a primary site above it in the site hierarchy. Also, a secondary site can have no sites beneath it.


SQL Server Configurations That Affect SMS

The following configurations in SQL Server affect the working of SMS in any primary or central site.

Sort Order

SMS will use the same sort order and character set as the SQL Server to execute queries and sort data.

SQL Login ID

You must have an SMS SQL Login ID to set up a site as a primary or a central site. This login ID is used during the SMS Setup program as well as to access the site database on the SQL Server after SMS is set up and in operation. In many cases the login ID will be SA, because the SMS administrator is usually also the SQL Server administrator.

Site Database Devices

SMS requires that each site have its own database and that the transaction log be on its own device. The site database devices and the database itself can be created in two ways:

  • The SMS Setup program can create the database and transaction log devices and can also create the database, if the site server has SQL Server installed on it. To do this, the SMS login ID must have system administrator privileges on SQL Server.
  • If the SQL Server is on a remote machine, then you must create the database devices before running the SMS Setup program, which will create the site database on these existing devices. In this case, the SMS login ID must have Create Database, Dump Database and Dump Transaction permissions on the master database. This enables the SMS Setup program to create and maintain the site database.

    Caution SMS will delete all objects on any database that exists on these devices. SMS requires a database and corresponding transaction log for its own use. Any existing data will be deleted prior to creating a site database on the specified devices on SQL Server.

tempdb

The size of tempdb is dependent on the number of computers in a particular site and all its subsites from which inventory will be collected and stored in SQL Server. A larger tempdb improves performance for queries that contain sorts. In general, if there are 1,000 computers on a site, a size of 5 to 10 MB is recommended. The default size of tempdb is 2 MB, and it resides on the master device. It is better to alter the size of tempdb on other devices than to increase its size on the master device. If a site heavily uses SMSVIEWS, the size of tempdb should be appropriately increased to accommodate query or view processing.

User connections

SQL Server should have at least 5 user connections configured separately for use by SMS. In practice, it is better to have at least 10 to 15 user connections set aside for SMS alone.

Memory

The optimum setting depends on how much RAM is installed on SQL Server and what other applications are running on the SQL Server machine. On a dedicated SQL Server with 32 MB of physical RAM, you can configure 16 MB to SQL Server. This would enable Windows NT Server to have enough memory to run its processes and would prevent page thrashing.

Open objects

For SMS, open objects on SQL Server should be configured for 5,000 to 10,000.

Locks

For SMS alone, the default configuration of 5,000 locks on SQL Server should be enough. However, if the server has other active databases on it, then this configuration should be adjusted appropriately.

Time synchronization

If SQL Server is on a remote machine, the SMS site server and SQL Server should be synchronized with the current time on the site server. On Windows NT, use the net time command.

Upgrading SQL Server and SMS

There are some nuances when upgrading SMS and SQL Server to their respective new versions. These can be summarized as follows:

  • SMS 1.0 is compatible with SQL Server 4.21a servers.
  • SMS 1.1 is compatible with SQL Server 6.5, SQL Server 6.0, and SQL Server 4.21a.
  • SMS 1.2 is compatible with SQL Server 6.5.
  • The order in which SMS and SQL Server are upgraded is important:

In case of SMS 1.0 and SQL Server 4.21a, the SMS sites should be first upgraded to SMS 1.1, and thereafter SQL Server must be upgraded to 6.0. This is because the SQL Server 6.0 version is incompatible with SMS 1.0.

SQL Server 6.0 can be upgraded to 6.5 as long as the site servers are all running SMS 1.1.


Part 6 - Programming for Microsoft SQL Server

The articles in Part 6 contain information about how you can combine your corporate solutions with SQL Server by using a variety of programming applications:

  • Using SQL-DMO
  • Open Database Connectivity
  • Creating Win32 Applications
  • Data Access Objects
  • Remote Data Objects


Using SQL-DMO

SQL-DMO enables robust administration of complex distributed server environments.

SQL-DMO enables developers to quickly and easily develop a range of useful, customized SQL Server administration tools and interfaces for a multiserver environment. The unique power and flexibility of SQL-DMO can be applied to the full range of database management and database definition tasks such as production, performance tuning, and graphical representation of databases.

The following discussion of SQL-DMO code assumes an understanding of Visual Basic.

SQL-DMO is available for 32-bit Visual C++ and the 32-bit version of Visual Basic or Visual Basic for Applications. SQL-DMO is also available for third-party products that are OLE 2.0 automation controllers—applications that can control other applications through OLE automation. The OLE object information is held in the Sqlole65.tlb type library file and is available to OLE automation controllers. On the Visual Basic Tools menu, the References command loads SQL-DMO information from the Sqlole65.tlb type library. Visual Basic applications can then use SQL-DMO objects to manage SQL Server.

All SQL-DMO applications must first create a SQLServer object and then connect to a server. The following Visual Basic code is the minimum template required for a SQL-DMO application.

Dim ServerObject As New SQLOLE.SQLServer
ServerObject.Connect "ServerName", "sa", "password"

Once connected, the SQLServer object can be used to refer to other objects and make changes to the server. The following example changes the "allow updates" configuration value by referring to and updating the Configuration object. The SQLServer object, shown as ServerObject, has a Configuration property that owns a collection called ConfigValues. This line of code uses the ConfigValues collection to specify the "allow updates" member and to change its CurrentValue property.

ServerObject.Configuration.ConfigValues("allow updates").CurrentValue = 1

If you want your application to modify database options, first refer to the specific SQL Server, then to the specific database before modifying the DBOption object's properties. The following Visual Basic code modifies the SelectIntoBulkCopy database option for the pubs database. This statement uses the Databases collection to refer to the pubs database.

ServerObject.Databases("pubs").DBOption.SelectIntoBulkCopy = TRUE

Certain SQL-DMO methods, particularly those that enumerate a range of values, return a result set in a QueryResults object. A QueryResults object must be declared first and then set to the return value of the enumeration method. Note that it is not possible to use the New operator with the QueryResults object in the Declare statement, because QueryResults objects are returned only as the result of a method that returns a result set. The QueryResults object has methods that allow you to step through each row and column in the result set.

Dim ServerObject As New SQLOLE.SQLServer
Dim Resultsobject As SQLOLE.QueryResults
ServerObject.Connect "servername","sa","password"
Set Resultsobject = ServerObject.EnumPublicationDatabases
Debug.Print Resultsobject.GetColumnString(1,1)

You can create a database and add tables, columns, and other database components by declaring new objects, setting essential properties, and then adding the new object to the appropriate collection. For example, a Column object has three essential properties (Name, Datatype, and Length) that must be specified before the Column object can be added to the Columns collection, as shown in the following code sample. Other optional properties, such as Identity, also must be set before the Column object can be added to the Columns collection. These properties cannot be changed once the object has been added to the collection. Other properties, such as the ID property, are controlled by the system.

Dim NewColobject as New SQLOLE.Column
NewColobject.Name = "OrderCategory"
NewColobject.Datatype = "char"
NewColobject.Length = 2
ServerObject.Databases("SalesDB").Tables("Orders").Columns.Add NewColObject

SQL-DMO error handling is consistent with Visual Basic error handling. You can trap SQL-DMO errors using the Visual Basic On Error Goto statement, as shown in the following procedure:

Sub ConnectToServer
On Error Goto MyErrorHandler
Dim ServerObject As New SQLOLE.SQLServer
ServerObject.Connect "ServerName", "sa", "password"
Exit Sub
MyErrorHandler:
MsgBox "The connection failed with error number " + str(Err.Number)
End Sub

Errors are handled differently in Visual C++. Each function returns a status value that you can use with a macro to obtain the error number and message.

The ServerGroup and RegisteredServer objects are new in Microsoft SQL Server 6.5. You can use these objects to write multiserver applications, where instructions are applied to all the servers on your network. The server groups and registered servers information is stored in the Registry of the system running SQL Server. You can use the following code sample to update the statistics for all tables on all the registered servers on your network.

Dim ServerGroupObject As New SQLOLE.ServerGroup
Dim RegisteredServerObject As New SQLOLE.RegisteredServer
Dim SQLServerObject As New SQLOLE.SQLServer
Dim DatabaseObject As New SQLOLE.Database
Dim TableObject As New SQLOLE.Table
For Each ServerGroupObject In ServerGroups
  For Each RegisteredServerObject In ServerGroupObject.RegisteredServers
   SQLServerObject.Connect RegisteredServerObject.Name, "sa", ""
   For Each DatabaseObject In SQLServerObject.Databases
    For Each TableObject In DatabaseObject.Tables
      TableObject.UpdateStatistics
    Next
   Next
   SQLServerObject.Close
  Next
Next


SQL-DMO Sample Solutions

You can use SQL-DMO to develop customized SQL Server administration solutions. This article suggests a range of applications that can be developed by using SQL-DMO to enhance SQL Server.


An Application for Testing Backups

You can create an interface used for automating database consistency checks and running backups, similar to the SQLMaint utility.

You can include customized features such as the ability to start and stop SQL Server. Visual Basic programs can easily check the day and time, which means that the interface could change the type of backup depending on the day of the week. Database dumps could occur on Friday and transaction log dumps on Monday through Thursday. Because the backup process cannot verify the quality of the tape or disk used, it is a good idea to occasionally restore a database from a backup to a test server and check the consistency of the data. This restoration process can be built into the Visual Basic application as a safeguard, as well as to simplify the process in the event of a true media failure.

The following illustration shows a Visual Basic interface that allows you to back up, restore, verify the backup, alert engineers when there are errors, check the efficiency of a range of procedures, and send e-mail reports.

First, you use the Database object's consistency checking methods to check the integrity of the database. Then, you use the Dump method to back up the database. The backup details can be stored in the Backup object and used with the Database Dump method. You can use the Operator and Alert objects to send e-mail. Restore is handled by the Database object's Load method. You can use Visual Basic tools to time stored procedures called with the Database object's ExecuteWithResults or ExecuteImmediate methods, or you can obtain the efficiency information within the stored procedure and return it to the application.


An Application for Testing Load Balance

You can create a test that helps determine the best strategies for load balancing a SQL Server system for optimum performance.

When you are working with Visual Basic to create a new database system, you may find that you frequently start and stop the SQL Server and rebuild a database from scratch, perhaps with only a few changes. Visual Basic is an ideal platform for writing a test-harness (a set of simultaneous processes derived from a typical real-time system). The test-harness application can initiate simultaneous user applications or use a script to simulate the keystrokes and mouse movements of an end user. This type of application is similar to a SQL script.

The SQL-DMO application contains code for all the objects that make up the database to drop, create, and insert into a collection. These objects include tables, indexes, columns, users, views, triggers, options, and configurations. You can test stored procedures using the ExecuteImmediate or ExecuteWithResults method, or you can simulate multiple instances of an application using the Visual Basic Shell command.


An Application for Transferring Data

You can create an application that uses SQL-DMO to build a database and to insert rows using data from another source (such as a mainframe or hardware that generates statistics). The program could retrieve data through a third-party control, driver, or gateway.

You can use Visual Basic to read the data and manage simple insertion of data using the Database object's ExecuteImmediate method to insert the data.

This is an example of where it may be more appropriate to use ODBC or DB-Library. The decision to use ODBC or DB-Library depends on whether the application requires only data manipulation tasks. If the application requires mostly data definition tasks, then SQL-DMO is more suitable.


A Customized Interface for Replication

You can create a replication interface that automates the process of setting up replication and that provides the user with additional information about the SQL Server installations.

To create a replication interface, you set up a publisher and a subscriber, and then you create publications. To set up a publisher, you set the SQLServer object's distribution properties and use the RemoteServer object and its SetOptions method to allow remote servers to subscribe. To set up a subscriber you use the RemoteServer's SetOptions method to subscribe to a remote server. You can add new Publication, Article, and Subscription objects to the relevant collection and then use the RemoteServer's Subscribe method to start replicating data. The RemoteServer object's SubscriberInfo object stores information that relates to the distribution schedule. The interface, created with Visual Basic, can be used to control the creation and management of the replication objects.


A Graphical Interface for Building Databases

You can create a graphical user interface that allows a user to build a custom database by clicking buttons and selecting table names from a list.

Many small companies need a unique database for their business. Frequently, database functions are similar for different businesses. For example, the appointment database used by a dentist, a psychiatrist, and a financial consultant may differ only in the table and column names. Information about an appointment can be stored in a patient table, a client table, or a customer table, depending on the type of business. A company may prefer to have a standard solution rather than to pay for a customized system. You can use SQL-DMO to create an interface that will build a working database, which you can then modify to meet the needs of specific clients.

To build an interface that creates custom databases, you create an interface that accepts descriptive names for columns and tables for one or more database scenarios, such as an appointment database. The bulk of the code creates and inserts columns, tables, triggers, and stored procedures using the appropriate collections.


An Application for Ensuring Security

You can create an automated system that creates groups and assigns permissions based on responses to queries made by other applications or data such as organization charts or job title lists.

To create an application that sets up security measures for a database system, you can use Visual Basic file I/O, OLE, or an API to retrieve information from the organization chart or other file or application. You can then use this information to create Login, User, or Group objects and insert them into the Logins, Users, or Groups collections. Permissions are then assigned by using the Grant method for Table, Database, or StoredProcedure objects.


A Graphical Interface for a Database's Table Relationships

You can create an interface that draws a graphical representation of a database, its tables, and relationships.

The following example interface shows the relationships between tables in a database. You can iterate through all the collections and objects in the Database object and then use Visual Basic controls to display the information graphically.


An Application for Testing Index Performance

You can create an application that systematically drops and rebuilds indexes using different columns and different orders and that measures and records the performance of each new index format by using a test-harness application (a set of simultaneous processes derived from a typical real-time system).

Before programming, you must identify the type and frequency of procedures requested by clients and create a representative sample of stored procedures. You can then write an application that adds and removes Index objects based on different permutations of a table's columns. You can identify the table's columns by iterating through the Columns collection. Then, the application can execute the representative sample of stored procedures using the ExecuteImmediate method and measure the execution time for each index. You can use this tool on many database systems to identify the combination of indexes that provides the best results.


A Multiserver Excel Macro

The Multi.xls application demonstrates how SQL-DMO can be used to create a multiserver backup macro in Microsoft Excel. The application backs up all the databases on a network to a central file share. Providing the server has been registered, the application connects to and backs up all the databases. Then, it calculates the percentage of space used and displays the results in an Excel spreadsheet. You can extend this simple application to perform complex backup strategies and chart the use of resources.

Because this application backs up to a network share, you must give the MSSQLServer service a domain system account that has write access to the file share on every server.

This application is stored on your BackOffice Resource Kit CD-ROM as Multi.xls.

The results are generated on the Excel worksheet as shown in the following illustration.


Future Direction

Microsoft continues to enhance SQL-DMO as a development tool. SQL-DMO will continue to support SQL Server features. For example, when new SQL Server features are added to replication, new SQL-DMO objects or methods will be created to represent these new features.

SQL-DMO will also continue to support the Microsoft Component Object Model (COM). The COM standard has recently introduced the Distributed COM component, which supports simultaneous calls from local or remote clients. Future releases of SQL-DMO will include Distributed COM components.


Open Database Connectivity

The ODBC SQL Server driver enables you to create ODBC client/server applications that take maximum advantage of Microsoft SQL Server.

The Microsoft Open Database Connectivity (ODBC) interface enables you to create applications that are interoperable with multiple database systems. The ODBC SQL Server driver enables you to create ODBC client/server applications that take maximum advantage of Microsoft SQL Server.

This article discusses:

  • Microsoft SQL Server ODBC driver versions.
  • ODBC ANSI upgrade changes from SQL Server 6.0 to 6.5.
  • Differences in SQL behavior between ODBC, ISQL, DB-Library, and SQL Enterprise Manager.


Microsoft SQL Server ODBC Driver Versions

The following table shows which versions of Microsoft SQL Server ODBC drivers shipped with different versions of Microsoft SQL Server. It also lists the operating system versions with which the drivers are certified to run, and the versions of SQL Server with which they are certified to work.

Driver version | Date | Shipped with | Supported SQL Servers | Supported OS
1.02.3231 | 10/8/93* | OS/2 SQL Server 4.2b | Microsoft OS/2 SQL Server 1.11 to 4.2b Sybase SQL Server 4.0 to 4.9.2 | Windows 3.1, Windows for Workgroups 3.11
1.02.3731 | 1/26/94* | SQL Server 4.21 | Microsoft OS/2 SQL Server 1.11 to 4.2b Microsoft SQL Server for Windows NT 4.20 to 4.21 Sybase SQL Server 4.0 to 4.9.2 | Windows 3.1, Windows for Workgroups 3.11
2.00.1912 | 7/14/94 | SQL Server 4.21a | Microsoft OS/2 SQL Server 4.2 to 4.2b Microsoft SQL Server for Windows NT 4.2 to 4.21a | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.1, 3.50, 3.51
2.50.0121 | 6/7/95 | SQL Server 6.0 | Microsoft SQL Server 4.21a and 6.0 | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.50, 3.51, Windows 95
2.50.0126 | 8/17/95 | SQL Server 6.0 Service Packs 1, 2, and 3 | Microsoft SQL Server 4.21a and 6.0 | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.50, 3.51, Windows 95
2.65.0201 | 4/3/96 | SQL Server 6.5 | Microsoft SQL Server 4.21a to 6.5 | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.50, 3.51, 4.0, Windows 95
2.65.0213 | 7/30/96 | SQL Server 6.5 Service Pack 1 | Microsoft SQL Server 4.21a to 6.5 | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.50, 3.51, 4.0, Windows 95
2.65.0240 | 12/30/96 | SQL Server 6.5 Service Pack 2 | Microsoft SQL Server 4.21a to 6.5 | Windows 3.1, Windows for Workgroups 3.11, Windows NT 3.50, 3.51, 4.0, Windows 95
* The 1.02.3231 and 1.02.3731 drivers are no longer shipped with any Microsoft products and are considered obsolete. They were ODBC version 1.0 drivers, and as such, only had Win16 drivers.

Customers who have the SQL Server versions listed above will have the corresponding ODBC driver version in the SQL Server client utilities. The drivers are also shipped with several applications or development languages, such as Microsoft Office, Visual Basic, and Visual C++.

Users can also obtain self-extracting zip files of drivers from ftp://ftp.microsoft.com/developr/odbc/public.

File name | Contains
Sqldrv.exe | 2.00.1912 driver
Sqlsrv32.exe | 2.50.0126 driver
Ssrv6532.exe | Win32 version 2.65.0201 driver
Ssrv6516.exe | Win16 version 2.65.0201 driver

The 2.50.0126 SQL Server driver is also included in the SQL Server 6.0 Service Packs 2 and 3.


ODBC ANSI Upgrade Changes from SQL Server 6.0 to 6.5

ODBC ANSI Upgrade Changes from
SQL Server 6.0 to 6.5

This section discusses changes in behavior that are introduced when you upgrade from Microsoft SQL Server version 6.0 and its associated Microsoft ODBC drivers to SQL Server 6.5 and its associated Microsoft driver. If you are using ODBC drivers other than Microsoft ODBC drivers, consult the documentation from your driver vendor.


Service Pack 2 and Later

There are two new backward compatibility features supported in the ODBC driver included in SQL Server 6.5 Service Pack 2. The first disables the use of ANSI quoted identifiers by the driver. This allows an application to have character literals surrounded by double quote characters ("").

The second disables ANSI null semantics, ANSI padding, and ANSI warnings. These are the ANSI settings that are enabled by default in the SQL Server 6.5 driver. Refer to the SET statement in the Microsoft SQL Server Transact-SQL Reference for details on these ANSI options.

The default for these features is to have them enabled; ANSI behavior is the default.

To disable either or both of these options, use one of the three following methods:

Uncheck the appropriate check box(es) in the DSN configuration dialog Options extension. This is only effective when connecting using that DSN.

Add "QuotedId=NO" and/or "AnsiNPW=NO" to the attribute string supplied to SQLConfigDataSource.

Use SQLSetConnectOption prior to connection using the option and values defined in the Odbcss.h file included in Service Pack 2.


Before Service Pack 2

When a version 2.65.0201 or 2.65.0213 ODBC driver connects to a version 6.5 server, it sets the following options with SQL Server:

SET QUOTED_IDENTIFIER ON
SET TEXTSIZE 2147483647
SET ANSI_DEFAULTS ON
SET CURSOR_CLOSE_ON_COMMIT OFF
SET IMPLICIT_TRANSACTIONS OFF

The net effect of setting these options is that when the 2.65.0201 or 2.65.0213 drivers are connected with a version 6.5 server, they will operate with three ANSI options turned on that were not turned on in earlier environments. The settings that will cause changes in behavior from those observed in the SQL Server 6.0 drivers are:

SET ANSI_NULLS ON
SET ANSI_PADDING ON
SET ANSI_WARNINGS ON

These behaviors will not show up in DB-Library-based applications such as ISQL/w, Enterprise Manager, isql, and so forth, unless the user has also issued the settings listed above.

SET ANSI_NULLS ON

With the SET ANSI_NULLS ON setting active, SQL statements cannot use the =NULL or <>NULL operators to compare for nulls; they must use IS NULL or IS NOT NULL. For example, in the following ISQL/w script:

create table TestNull (cola int NOT NULL, colb char(3) NULL)
go
insert into TestNull values (1,'aaa')
insert into TestNull(cola) values (2)
go
SET ANSI_NULLS OFF
go
select * from TestNull where colb = NULL
go
SET ANSI_NULLS ON
go
select * from TestNull where colb = NULL
go

The first select returns one row with colb = NULL, the second select returns no rows. This can also affect commands in stored procedures if their WHERE clauses attempt = or <> comparisons using parameters passed in with null values.

SET ANSI_PADDING ON

When enabled, ANSI_PADDING prevents any trailing spaces or nulls from being truncated from varchar and varbinary values. It also affects fixed-length data types such as char or int. If the user specifies that columns of fixed-length data types (char, int, tinyint, smallint) can be NULL, ANSI_PADDING causes these columns to be padded in the event of a null value.

The following script can be used to illustrate the effect ANSI_PADDING has on values, regardless of whether they are binary or varbinary values:

create table padtest (vc5 varchar(5) not null, c5 char(5) not null, cn5     char(5) null)
insert padtest values('abc','abc','abc')
insert padtest values('abc' +space(1),'abc' +space(1),'abc' +space(1))
select vc5,c5,cn5 from padtest
go
select datalength(vc5), datalength(c5), datalength(cn5)
from padtest
go

The following table illustrates the results you will receive when executing this script when ANSI_PADDING is ON and when ANSI_PADDING is OFF.

 | Varchar (vc5) | Char (c5) | Char nullable (cn5)
ANSI_PADDING ON | No change 'abc' (3) 'abc<sp>' (4) | Padded 'abc<sp><sp>' (5) 'abc<sp><sp>' (5) | Padded 'abc<sp><sp>' (5) 'abc<sp><sp>' (5)
ANSI_PADDING OFF | Truncated 'abc' (3) 'abc' (3) | Padded 'abc<sp><sp>' (5) 'abc<sp><sp>' (5) | Truncated 'abc' (3) 'abc' (3)

If columns in a table are created while ANSI_PADDING is enabled, those columns will always exhibit the padding behavior, whether or not ANSI PADDING is on or off in the future. However, if you create new columns in that table while ANSI_PADDING is disabled, the new columns will never exhibit padding behavior.

SET ANSI_WARNINGS ON

The SET ANSI_WARNINGS ON setting will cause the Microsoft ODBC driver to generate messages under new conditions. One condition is that if an aggregate function encounters nulls it will generate a warning. For example, the following command referencing the TestNull table created above:

SQLExecDirect(hstmt,
"select max(colb) from TestNull)",
SQL_NTS);

will return SQL_SUCCESS_WITH_INFO, and a call to SQLError will return:

szSqlState = "01003", *pfNativeError = 8153,
szErrorMsg="[Microsoft][ODBC SQL Server Driver][SQL Server]
            Warning, null value eliminated from aggregate."

Another example is that an insert or update that attempts to put in a value whose length is larger than that allowed by the column will fail, whereas with ANSI_WARNINGS set off, the operation would continue and the value would be entered after the data was truncated. For example, with the TestNull table defined above and the 6.5 driver, the following:

SQLExecDirect(hstmt,
            "insert into TestNull values (3, 'abcd')",
            SQL_NTS);

will return SQL_ERROR, and a call to SQLError returns:

SQL_NO_DATA_FOUND
szSqlState = "22001", *pfNativeError = 8152,
szErrorMsg="[Microsoft][ODBC SQL Server Driver][SQL Server]
Column 'colb' of table 'pubs.dbo.TestNull' cannot
accept 4 bytes (3 max)."
szSqlState = "01000", *pfNativeError = 3621,
szErrorMsg="[Microsoft][ODBC SQL Server Driver][SQL Server]
Command has been aborted."


Differences in SQL Behavior Between ODBC, ISQL, DB-Library, and SQL Enterprise Manager

When you use the ODBC drivers that ship with SQL Server version 6.0 or later, SQL Server commands sometimes may appear to work differently in ODBC clients from how they work in either DB-Library clients or the SQL Server client utilities, such as isql, ISQL/w, and the Enterprise Manager query analyzer window. In most cases, these differences are simply due to options set by the Microsoft ODBC SQL Server driver using the Transact-SQL SET command, and if the same options are set in the DB-Library clients, they exhibit the same behavior as the ODBC driver.

The ODBC standard is closely matched to the ANSI SQL standard, and ODBC applications expect the behavior of an ODBC driver to match the standard behavior. In order to make its behavior conform more closely with that defined in the ODBC standard, the Microsoft ODBC SQL Server driver version 2.50.0121 always issues the following Transact-SQL SET commands.

When you connect to SQL Server version 4.21a:

SET TEXTSIZE 2147483647
SET ARITHABORT ON

When you connect to SQL Server version 6.0:

SET ANSI_NULL_DFLT_ON ON
SET TEXTSIZE 2147483647
SET QUOTED_IDENTIFIER ON
SET ARITHABORT ON

The 2.65.0201 driver, which ships with SQL Server 6.5, will set the same options when connecting to version 4.21a and 6.0 servers. When the 2.65.0201 driver connects to a SQL Server 6.5 server, it will set the following options:

SET QUOTED_IDENTIFIER ON
SET TEXTSIZE 2147483647
SET ANSI_DEFAULTS ON
SET CURSOR_CLOSE_ON_COMMIT OFF
SET IMPLICIT_TRANSACTIONS OFF

The Microsoft ODBC SQL Server driver issues these commands itself; the ODBC application does nothing to request them. Setting these options allows ODBC applications using the driver to be more portable, because the driver's behavior then matches that defined by the standard.

ODBC applications should not change these SET options, except for the three exceptions discussed in the following paragraph. Not only does the driver depend on these options to comply with the ODBC standard behavior, it also assumes that these options are set when it generates SQL commands that it sends to the server. For example, the driver may put double quotation marks around object names in its generated SQL statements to handle objects created using quoted identifiers, and whose names are only legal if enclosed in quotation marks. If the application has turned off the QUOTED_IDENTIFIER option, then these generated SQL commands will get syntax errors from the server.

ODBC applications using the 2.65.0201 or 2.65.0213 drivers can turn off three of the ANSI options normally set on by the driver. They are:

SET ANSI_NULLS OFF
SET ANSI_PADDING OFF
SET ANSI_WARNINGS OFF

The application can do this by simply executing the appropriate SET command, for example:

SQLExecDirect(hstmt, "SET ANSI_NULLS OFF", SQL_NTS);

If the code affected by the ANSI options is in a stored procedure, the appropriate SET commands can alternatively be added at the top of the stored procedure. In this case, the ANSI option would be turned off during the execution of the stored procedure, then return to the setting requested by the client when the procedure quits. This would allow the procedure writer to control the environment in the procedure without affecting the general settings requested by each client.

The 2.65.0240 driver that ships with SQL Server 6.5 Service Pack 2 gives users greater control over what specific ANSI options are set by the driver. When a user defines a data source using the 2.65.0240 driver, there is a check box for turning on or off the setting of QUOTED_IDENTIFIERS, and another for turning on or off ANSI_NULLS, ANSI_PADDING, and ANSI_WARNINGS. Users can also set these options on or off when creating a data source through SQLConfigDataSource. In addition, the 2.65.0240 driver supports driver-specific connection options to control these at connect time. See the SQL Server 6.5 Service Pack 2 Readme.txt for more details.

Before assuming that there is a true difference in behavior between the Microsoft ODBC SQL Server driver and DB-Library applications, you should run the DB-Library test with the same SET options as you use with the ODBC driver.


Creating Win32 Applications

SQL Server not only manages information but also makes that information easy to access and easy to use with other applications.

Windows 95 and Windows NT are both 32-bit operating systems that implement the Win32 API and free programmers from the restrictions of 16-bit programming. Under Windows NT, Win32 applications automatically support symmetric multiprocessing (SMP) and can be easily recompiled for high speed RISC processors like DEC Alpha and PowerPC.

SQL Server is designed not only to manage information, but also to make that information easy to access and easy to use. Hundreds of leading applications support SQL Server today by using ODBC and DB-Library application program interfaces (APIs). Both ODBC and DB-Library provide everything you need to build powerful client/server applications.

ODBC allows you to create portable DBMS applications. ODBC is an industry-standard, database-independent, API for creating applications that support multiple datasources on Windows 95, Windows NT, and Windows 3.x platforms. ODBC drivers are also available for OS/2 and leading UNIX environments.

DB-Library provides the same basic functionality as ODBC, but also includes some special functions for high-speed data loading (bulk copy), and image and text operations.

Note You can build 32-bit applications with either DB-Library or ODBC, but remember that ODBC is more widely supported.

The following illustration shows their relationship to each other and to SQL Server.

Both DB-Library and ODBC communicate with SQL Server by using the Tabular Data Stream (TDS). TDS is the self-defining protocol used by Microsoft SQL Server to transfer requests and responses between the client and the server. The Net-Library provides a transport-independent method of sending TDS across a physical network connection. As you can see from the preceding illustration, ODBC is not layered on top of DB-Library and therefore provides the same performance as DB-Library applications.


Overview of DB-Library

DB-Library consists of over 180 functions that allow your application to communicate with SQL Server. The following illustration shows the basic structure of every DB-Library program. Most DB-Library programs only use between 10 and 15 functions.

Communication between the client applications and SQL Server are managed by using a DBPROCESS structure as follows:

dbopen allocates and initializes the DBPROCESS structure. The user name, password, application name, and other "per connection" parameters are stored in the login record.

Login records are created by calling dblogin. Since you now have a connection to SQL Server, you can start sending SQL statements.

dbcmd copies the SQL statement into the command buffer.

The statement is not actually sent across the network to the server until dbsqlexec is called. At this point the SQL statement is compiled, optimized, and executed. SQL Server can return multiple result sets if multiple SQL statements were sent in a single batch or stored procedure.

To retrieve the result set, call dbresults.

Each row in the current result set is fetched by calling dbnextrow until dbnextrow returns NO_MORE_ROWS. This process is repeated by calling dbresults until it returns NO_MORE_RESULTS. NO_MORE_RESULTS means that you have processed every SQL statement in the command batch or stored procedure.

When the application is finished, you can close your connection by calling dbclose. This will deallocate the DBPROCESS on the server and release the resources it held on the server.

The client application can now terminate by calling exit.

SQL Server calls a function in your application whenever it needs to send a message to the client or notify the client of an error. These functions are installed with dberrhandle and dbmsghandle and are not shown in the illustration.


DB-Library Demo

A simple DB-Library character-based (Win32 console) application called Firstsql.cpp is on your BackOffice Resource Kit CD-ROM. This application connects to a SQL Server and requests a complete list of authors sorted by the author's last name from the pubs database. To run this demo, you need to have the pubs sample database installed on your server.


The Advantages of Win32

Dynamic-link libraries (DLLs) work very differently under Win32. In Windows 3.x, each 16-bit DLL has its own data segment where all static and global variables are stored. This single data segment is shared across all processes using the DLL. Any memory allocated in the DLL is allocated from the DLL's data segment and is available to all calling processes. This design makes it very easy to share data among multiple processes.

The 16-bit DB-Library for Windows 3.x (W3dblib.dll) maintained the DB-Library connections as a linked list within this single, shared data segment. This required programmers to call dbinit before any other DB-Library function calls to initialize data structures, and dbwinexit to clean up when the application was done.

When Windows runs in protected mode, it uses an indirect method of segment addressing that allows the segment to be moved around by Windows without fear of invalidating any far pointers. Many applications still make unneeded calls to DBLOCKLIB and DBUNLOCKLIB. If they are still lingering in your code, delete them.

In Win32, DLLs are mapped into the address space of the calling process when the DLL is loaded by the process. This means that each process has a separate copy of the DLL's global and static data.

Each Win32 process enjoys a 4 GB virtual address space. Two gigabytes are reserved for the system and 2 GB are available for your application. The 32-bit "flat" memory model frees you from the limitations of Intel's 64K physical segment size. The flat memory model also eliminates the need to call MakeProcInstance and FreeProcInstance to create an address "thunk" for callback functions. Edit controls now can hold almost 2 GB of text, and list boxes can have more entries than your users are willing to scroll through. Win32 DB-Library supports dbprhead and dbprrow. These functions allowed MS-DOS programmers to display the output of any query to STDOUT, but they were not available on Windows 3.x because Microsoft does not support the concept of STDOUT. Since Win32 supports both graphical- and character-based (console) applications, they are now available and you can take advantage of them in your applications.


Multitasking

Windows 3.x can run multiple applications at the same time as long as all of the programs are well behaved. Windows 3.x is a cooperative multitasking environment. Each application must tell the system that it has finished processing, before any other application can start, by calling GetMessage. If an application does not yield control, then the user will not be able to switch to another program.

How do you prevent an application from hogging the system? The two basic approaches are to use PeekMessage or a timer.

PeekMessage allows the application to continue processing until another application needs to process a message. After performing a small part of the job, your application must yield to Windows by using WaitMessage. This gives other programs a chance to use the system. When the system is available again, you can process another small part of your job.

When you use a timer, the application executes a chunk of the job whenever you receive a message from the timer.

Obviously, both of these approaches add unnecessary complexity to the application. Applications are not always made up of a series of discrete tasks. Even when an application is easily divided into discrete tasks, you must still keep track of what work has been completed and deal with any errors.

Cooperative multitasking can sometimes make it more difficult to develop client/server applications. If an application makes a synchronous call to some function that performs a lengthy process, Windows 3.x appears to "freeze" until that function finally returns and can yield control back to Windows 3.x. Since synchronous functions like dbsqlexec do not return until the specified query has been compiled and executed, complex queries against very large databases may take some time to complete. SQL Server provides functions that allow any application to communicate asynchronously. dbsqlsend sends a command batch to SQL Server but does not wait for the database processing to complete before it returns control to the caller. It returns it immediately. You can call dbdataready periodically to see when your command has finished, and then call dbsqlok before processing the result set. This makes it much easier to create very responsive applications on the Windows 3.x platform.

Windows 95 and Windows NT provide preemptive multitasking. This means that the operating system can preempt your program at any time, give the CPU to another process, and then return control back to your program's execution without your knowledge or permission. Preemptive multitasking takes the burden off the application developer and puts it on the operating system—where it belongs. Win32 applications do not monopolize the system. The scheduler will preempt them whenever a higher priority process is waiting.


Multithreading

Multithreading means that a program can create multiple execution threads within a single process to service multiple user requests at the same time. A program, or process, is just a set of instructions and the data that those instructions operate on. Processes can own resources like CPU time, files, I/O devices, and memory. In Win32, every process contains at least one thread of execution. A thread is sometimes referred to as a unit of execution because the scheduler does not schedule processes—it only schedules threads. Windows 3.x applications never have more than one thread.

Threads are function calls that execute asynchronously with respect to their creator. Each thread is scheduled based on its priority. It will be run for a predetermined period of time, known as a time quantum, or until a higher priority thread is available. New threads are created by calling CreateThread. The priority of any thread can be changed with SetThreadPriority. Threads can be terminated by calling ExitThread or TerminateThread. If your application uses any C run-time library functions, then you must use _beginthread and _endthread, and then link with the multithreaded C run-time library. This allows the C run-time library to properly initialize and maintain its state information on a per-thread basis. If you link with the single-thread library, you will introduce errors into your multithreaded program.

Creating new threads is fast and simple. How they are executed depends on the hardware and operating system you use. On a Windows NT SMP system, each thread could execute simultaneously on different processors. Under Windows 95, or on any single-processor system, the operating system will preemptively time slice your threads and rotate them with all the other threads waiting to be scheduled.

Threads allow more efficient use of resources. No longer do your programs have to start at the top and sequentially process each step before finishing at the bottom. You can create as many threads as an application needs and attack any problem in parallel. Creating threads is easy. The hard part is preventing multiple threads from interfering with each other.


Synchronizing Threads

How do you prevent thread collisions? Win32 provides powerful synchronization objects to coordinate the work of multiple threads. Each synchronization object is in either a signaled or nonsignaled state. Signaled means that the object is available. Nonsignaled means that it is unavailable or in use by another process or thread.

The most common use for synchronization objects is to protect resources, like global variables, that are shared among multiple threads. Synchronization objects let you serialize access and ensure that one thread does not start reading the value of a character array, for example, until the other thread has finished writing to it.

The simplest form of mutual exclusion is a Critical Section. Critical Sections provide mutual exclusion between multiple threads within a single process. Only one thread can get exclusive access to the Critical Section by using EnterCriticalSection. All of the other threads are held in an efficient wait state, not scheduled by the operating system, until they are able to get access to the Critical Section. When they are finished, they call LeaveCriticalSection and let another thread get in. Critical Sections are global variables whose value is set by the operating system (Kernel) rather than by the user. Mutexes are similar to Critical Sections, but provide mutual exclusion across processes on the same machine. Semaphores allow you to throttle the number of users accessing a particular resource. When the semaphore is created, the maximum number of simultaneous users is specified. When the user calls WaitForSingleObject and the usage count is less than the maximum, the system decrements the usage count and wakes up the thread. Critical Sections, Mutexes, and Semaphores are generally used to control access to data. Events are used to signal that some task has been completed or a task is ready to be started. The following illustration shows these concepts.


Multithreaded SQL Server Applications

Preemptive multitasking makes it easy to implement asynchronous query processing. If you have multiple threads sharing a connection, then you have to serialize access to the shared DBPROCESS.

Most multithreaded applications open multiple connections to the server. Opening a connection to SQL Server is relatively fast and inexpensive from a resource standpoint. Depending on your max worker threads configuration, each DBPROCESS only requires about 50K of memory.


Multithreaded SQL Server Demo

This example demonstrates how to create a multithreaded SQL Server application. Before you can run the demo, you must run Adduser.sql, included on the CD-ROM provided with this resource guide, from ISQL/w or SQL Enterprise Manager. This script will create 16 new users and grant them access to the various tables in the pubs database.

This multithreaded application will create up to 15 threads. Each thread will open a connection to SQL Server. None of the threads begins executing SQL statements until a manual reset event is signaled. In this case, the Win32 event acts like a traffic light. When the traffic light is "green," or signaled, each user starts sending SQL statements to the server.

By running your user interface on a separate thread with a higher priority, your users will perceive that your application is fast. Even with 15 users working on SQL Server, you can instantly and gracefully disconnect all threads by clicking Stop.

Clicking Stop resets the Win32 event object to the nonsignaled state and each thread disconnects from SQL Server and terminates by calling _endthreadex. The following illustration shows SQL Enterprise Manager.

The SQL Enterprise Manager Current Activity dialog box makes it easy to see who is using the server. To watch the SQL statements change while the demo runs, click Refresh.

To begin developing 32-bit applications for SQL Server, see the Microsoft SQL Server development libraries and documentation for ODBC, DB-Library, and Open Data Services, available with the SQL Workstation product, which also includes a complete single-user SQL Server, or MSDN Professional.


Data Access Objects

With Data Access Objects, you can manipulate databases in several database formats.

You can use Data Access Objects (DAO) to manipulate databases in either the native Jet database engine .mdb format or in other installable ISAM database formats, including Microsoft FoxPro, dBASE, Microsoft Excel, Btrieve, Paradox, and delimited Text.

In addition, you can use DAO to access Microsoft SQL Server and any other database that can be accessed with an ODBC driver using the same DAO code. This can be done through the Jet engine or directly through ODBC.

This article discusses deleting records containing NULLs using DAO.


Deleting Records Containing NULLs Using DAO

When you use DAO to attach a SQL Server 6.5 table, an attempt to delete records that contain one or more NULL values results in the following error:

Data has changed. Operation stopped.

The SQL Server 6.5 ODBC driver always sets the ANSI_NULLS option to ON on every connection that is to be ANSI compliant. This means that a search condition like 'WHERE <colname> = NULL' is always evaluated to FALSE. In accordance with the ANSI specification, the correct syntax when searching for NULLs is 'WHERE <colname> IS NULL'.

Consider a SQL Server table attached in Microsoft Access/Visual Basic that has NULL values. An attempt to delete a row that has one or more NULL fields will not succeed because Microsoft Access/Visual Basic uses the following syntax:

Delete from <tablename>
Where <colname1> = NULL And <colname2> = 'xxx'

Because the above search condition is always evaluated to FALSE, no rows will be affected by the delete and Microsoft Access/Visual Basic will display the message, "Data has changed. Operation stopped."

To work around this problem, do one of the following:

  • Update the NULL values to non-NULLs and then delete the record.
  • Add a timestamp (a SQL Server data type) column to the SQL Server table that does not allow NULLs, and copy the data from the existing tables to the new ones. Then, delete the existing tables and rename the new tables.
  • If using the 2.65.0240 SQL Server driver that shipped with SQL Server 6.5 Service Pack 2, deactivate the Use ANSI NULLS, Padding, and Warnings check box for the data source.


Remote Data Objects

Using Remote Data Objects with Microsoft SQL Server can mean high performance and flexibility when accessing remote database engines.

With Remote Data Objects (RDO) and the RemoteData control, your applications can access ODBC data sources without using a local query processor.

Note This is now possible with DAO 3.5 and ODBCDirect.

This can mean significantly higher performance and more flexibility when accessing remote database engines. Although you can access any ODBC data source with RDO and the RemoteData control, these features are designed to take advantage of database servers, like Microsoft SQL Server and Oracle, that use sophisticated query engines.

By using RDO, you can create simple cursorless result sets, or more complex cursors. You can also run queries that return any number of result sets, or execute stored procedures that return result sets with or without output parameters and return values. You can limit the number of rows returned and monitor all of the messages and errors generated by the remote data source without compromising the executing query. RDO also permits either synchronous or asynchronous operation so your application doesn't need to be blocked while lengthy queries are executed.

This article discusses how to call system stored procedures on SQL Server from RDO.


How to Call System Stored Procedures on SQL Server from RDO

SQL Server has a number of prewritten, stored procedures that are used to configure and administer your SQL Server. All of these procedures have the prefix sp_ that distinguishes them from user-written or application-written stored procedures.

In order to call these stored procedures from RDO, you must specify the master database—the database in which they reside. One effective way to do this is to explicitly reference the stored procedure in your Call syntax. For example::

{ ? = call master.dbo.sp_addlogin(?,?) }

Another method is to set the current database before creating and executing your stored procedure. The following example uses a prepared statement and assumes that pubs is your current database:

<Object>.Execute "Use Master"  'rdoConnection object
Set <Object> = <Object>.CreatePreparedStatement({call "sp_addlogin(?,?)}", strSQL)
<Object>.Execute               'rdoPreparedStatement object
<Object>.Execute "Use Pubs"    'rdoConnection object

To execute a stored procedure on SQL Server from RDO, perform the following steps:

Start a new project in Visual Basic. Form1 is created by default.

Add a Command button, Command1, to Form1.

Paste the following code into the General Declarations section of Form1.

Note You need to change your DATABASE, UID, and PWD parameters in the OpenConnection method.

Private Sub Command1_Click()

Dim en As rdoEnvironment

Dim cn As rdoConnection

Dim rs As rdoResultset

Dim strConnect As String

Dim strSQL As String

Set en = rdoEnvironments(0)

en.CursorDriver = rdUseOdbc

strConnect = "Driver={SQL Server}; Server=MyServer; " & _

"Database=pubs; Uid=sa; Pwd="

Set cn = en.OpenConnection(dsName:="", Prompt:=rdDriverNoPrompt, _

ReadOnly:=False, Connect:=strConnect)

Dim ps As rdoPreparedStatement

Note If you don't specify master in the following statement, you will get the error: "An invalid parameter was passed."

strSQL = "{ ? = call master.dbo.sp_addlogin(?,?) }"

Set ps = cn.CreatePreparedStatement("", strSQL)

ps.BindThreshold = 1024 'largest column that will be bound under ODBC.

Debug.Print ps.rdoParameters.Count

ps.rdoParameters(0).Direction = rdParamOutput

ps.rdoParameters(1).Direction = rdParamInput

ps.rdoParameters(2).Direction = rdParamInput

ps.rdoParameters(1) = "LoginID"

ps.rdoParameters(2) = "Password"

ps.Execute

Debug.Print ps.rdoParameters(0).Value

End Sub

Start the program or press the F5 key.

Click the Command1 button to execute the stored procedure. The parameter count and the output parameter will be displayed in the debug window.


Part 7 - Data Warehousing

Many Microsoft SQL Server customers are already using SQL Server for data warehousing. Part 7 discusses data warehousing and how you can begin implementing it for your enterprise. The following topics are included:

  • Online transaction processing (OLTP) and data warehousing
  • Data warehouse design
  • Star-schema design
  • Data marts
  • Architecture of a data warehouse
  • Constructing a data warehouse
  • Arcadia Bay demonstration


Data Warehousing

You can use SQL Server for data warehousing in your enterprise.

The widespread use of data warehousing has been one of the most significant developments, after the Internet, in the information technology industry. Data warehousing is the process whereby an organization extracts data from its production information systems, and also sometimes from external systems, and stores the data in data warehouses optimized for query access and decision support.

Databases have mainly been used for online transaction processing (OLTP) systems, characterized by speedy transactions and rapid updates of data. Decision support systems (DSS) or data warehouses, characterized by large amounts of historic data, are gaining in importance.


OLTP and Data Warehousing

An OLTP database is used for speedy, repetitive transactions, such as withdrawing money from a checking account or checking a balance in a savings account at an automated teller machine (ATM). Some of these transactions will change the amount of money in a customer's bank account, so the updates to the database must be quick and accurate. The format of the OLTP database, with its highly normalized tables, row-level or page-level locking, and minimal redundancy, is not optimal for the requirements of data warehousing decision support systems.

A data warehouse database is used for decision support, and queries may differ greatly from those issued to a comparable OLTP database. For example, if a corporate analyst determines that 10 percent of her company's clients are responsible for 60 percent of the revenue, she could institute some extra services for those clients. A data warehouse can help her determine what types of services would appeal to those clients. She could issue various nonrepetitive queries to the database. Unlike the ATM scenario, these queries will not alter the information in the database, so speedy updates requiring row-level or page-level locking are not an issue. The analyst's demands of the data warehouse are for information—lots of it—at a reasonable speed, despite a query structure that may be less than optimal.

Data warehouses are set up and operated differently from production OLTP systems. When discussing data warehousing, it can be helpful to understand what sets it apart from traditional OLTP databases.

The following table explains the differences between an OLTP database and a data warehouse.

OLTP database | Data warehouse
The data being updated is locked to provide a consistent view. | Data locking is not necessary because databases are typically read-only.
Updates are applied to the temporary file and create a lot of overhead in transaction logs and rollback logs. | Because data usually is not updated, transaction logs and rollback logs are not an issue.
Interquery parallelism can be effective, as it spreads executing queries across available processors. Each query is allocated to a single processor. | Intraquery parallelism can be effective, as queries are broken down into subtasks that are executed in parallel.
Database systems are designed around entities, relationships, functional decomposition, and state transition analysis. | Database systems are based on facts, dimensions, hierarchy, and sparsity.
Information in a database is viewed as an atomic transaction. | Information in a database is viewed as a "slice of time."
Information is locally consistent—it is defined in terms of one database. | Information is globally consistent—its definition is common to all the database members of the data warehouse system.
Information is gathered for detailed audit trails. | Information is provided to adequately depict the "big picture."
Relationships between entities are explicitly modeled. | Relationships between entities are implicitly modeled—fact tables exist at the cross section of dimensions.

Whereas an OLTP database should be highly normalized to ensure speedy transactions and minimal redundancy—an extensive index ensures minimal table scans and joins—a data warehouse has only a few tables and is generally denormalized. The number of tables and alternative join paths required for a basic DSS query would overwhelm the query optimizer of a standard OLTP database. OLTP databases build more indexes to resolve queries without scanning the entire table, thereby speeding a transaction. However, although indexing speeds queries, processing vast indexes slows down updating.


Data Warehouse Characteristics

The defining characteristics of a data warehouse are:

  • Subject-oriented design

    Data warehouses are organized around major subjects integral to the enterprise. A data warehouse concerns itself with subjects like customers, vendors, or products.

  • Nonvolatility of data

    Data in data warehouse databases is static. Data is loaded into the warehouse at one time and is processed there, but does not change as it is accessed for DSS queries.

  • Historical time value of data

    In a data warehouse, data is accurate in the context of a specific historical time.

  • Integrated data types

    Before it is loaded into a data warehouse, data from varied sources is integrated into one set format.


Star-Schema Design

Each DSS database, housing a few tables, is termed a data warehouse. The most popular design technique for this type of database is called dimensional modeling, or a star schema.

A star schema is made of two types of tables: fact tables and dimension tables. Fact tables are rows of indexed facts, usually numeric values. Dimension tables are denormalized descriptions of the facts. Fact tables and dimension tables are united by dimensional keys. Dimensional keys, like primary keys, are unique identifiers that connect a row in a fact table with one specific dimensional table. An optimal data warehouse database has long, thin fact tables and small, short, wide dimension tables. The following illustration depicts a simple warehouse star-schema model with one fact table and four dimensions. Some star-schema designs have as many as 25 to 30 dimensions and multiple fact tables.

The time table (Time_Table) is one of the distinguishing characteristics of the dimensional model. Functions relating to time are very important for decision support. For example, this fiscal year a marketing executive at a major flower distribution company has a reduced budget and must determine when to launch an ad campaign. She wants to compare sales of roses during the last three Christmas seasons with the sales of roses on February 14 and Mother's Day last year to determine how to best spend her advertising dollars.

As the following illustration shows, the marketer's decision support query would access information from the fact table, in this case sales (Sales_Table), and the four dimensions of store (Store_Dimension), time (Time_Dimension), product (Product_Dimension), and order (Order_Dimension).

Using the Store_Dimension, the marketer will determine the regions that are most lucrative. The Month entity of the Time_Dimension will indicate when buyers are most likely to buy flowers. The most popular breed of roses will be evident from Product_desc in the Product_Dimension. Also, the marketer may choose to work with a particular credit card company in promoting flowers if many customers charge flowers to credit, as evidenced by the Payment_type entity in Order_Dimension.

Standard SQL is limited to date arithmetic and date comparison. Databases used for data warehousing must be able to perform more complicated time calculations, including:

  • Time aggregation (the particular weeks that add up to the second quarter of the flower distributor's fiscal year).
  • Calendar conversion (ability to calculate leap year every fourth year).
  • Automatic conversions for data having different time valuations (for example, monthly advertising expenditures versus yearly sales).


Data Marts

Many Microsoft customers have preferred to implement data marts, which are a type of data warehouse with the following characteristics:

  • Subject oriented
  • Fewer dimensions
  • Limited data feeds
  • Quicker to implement (average from 3 to 6 months)
  • Easily accessible
  • Lower cost
  • Lower risk
  • Iterative development (allows prototyping)
  • Homogeneous group of users who share common business problems, metrics, or roles

Data marts are often specific to an organizational department, unit, or function. Data warehousing is a term that usually is applied to a decision support system that models an entire entity's business and data structure. Some data marts eventually grow or merge into a data warehouse. Another approach is for large enterprises to break a large data warehouse into several data marts, which send reports back to the central data warehouse repository. Or the central data warehouse can feed the data marts their information, in which case the data marts inherit from the data warehouse its business rules, sources, and semantics.


Architecture of a Data Warehouse

A data warehouse is composed of operational and external data sources, one or more databases, and one or more desktop data analysis tools. In the following illustration, data is extracted, scrubbed, transformed, loaded, aggregated, and replicated between the operational and external data sources (1) and the data warehouse (2). A subset of the data is loaded, and data is aggregated and replicated at the data mart level (3). Using desktop analysis tools (4), spreadsheets are built, reports are written, and data is analyzed.

The following is a list of the most popular Microsoft products that can be used to build and maintain data warehouses, as presented in the preceding architecture illustration.

  • SQL Server, TransAccess, and SNA Server can be used to load the data warehouses with operational data.
  • SQL Server relational database management system can be used as a data warehouse.
  • SQL Server, alone or combined with Internet Information Server, Microsoft Exchange, or SNA Server is an effective data mart.
  • Microsoft Access, Excel, Visual Basic, Visual C++, and Internet Explorer are used as desktop data analysis tools.


Constructing a Data Warehouse

Although not required, it can be useful to build a database strictly for analytical queries, separate from the transactional database. When a data warehouse is loaded, information from operations on a transactional database are transferred, often millions of records at a time. This volume of data overloads traditional normalized databases. Additionally, data warehouses generally don't need the added overhead of transaction logs, rollback logs, and incremental referential integrity checking inherent to transactional databases. The basic steps for the creation of a data warehouse are:

Plan a design.

Create tables.

Move data to the warehouse.


Planning a Design

When you decide to develop a data warehouse, you need to have a clearly defined business case. In this business case you should:

  • List the players.
  • Explain the expected value of the data warehouse to the enterprise.
  • Outline the framework and direction of the implementation process.
  • Define the enterprise's most vital business functions.
  • Evaluate the enterprise's overriding facts and subject-oriented dimensions.

Once you have built your business case, evaluate the available technology. You need the following:

  • One or more Windows NT servers
  • One or more SQL Server licenses
  • SQL Server data extraction or transfer tools
  • Microsoft decision support applications


Creating Tables

Once you have determined the data needs of the users of the data warehouse, based on the most vital business functions of the enterprise, you can begin to build a database using the basic principles of OLTP database construction. However, keep the following star-schema guidelines in mind:

  • Create many small tables for subject-oriented dimensions.
  • Use denormalized indexes.
  • Create one large fact table based upon common elements.


Moving Data to the Warehouse

The following three steps must be performed to move data into the warehouse:

Extract the data from the source database(s).

Load the data into the data warehouse.

Process the data in the data warehouse.

Microsoft SQL Server has three extraction, or transfer and processing, tools you can use to move data to the warehouse:

  • Bulk Copy Program (bcp) Utility

    The bcp utility is a command-prompt utility that can be used to extract data from the OLTP database and load it into the data warehouse database. The bcp utility will extract and load ASCII data quickly, but it will not process data once it reaches the data warehouse, and it is not as flexible as either of the other two options.

  • SQL Enterprise Manager

    SQL Enterprise Manager can be use to extract data from the OLTP database and load it into the data warehouse database (on the Tools menu, click Database/Object Transfer). Because it is a graphical tool, it is somewhat easier to use than the other two options, but it is an interactive tool and needs an operator present for certain steps. Like bcp, it does not process data once it reaches the data warehouse.

  • SQL Distributed Management Objects

    SQL Distributed Management Objects (SQL-DMO) can be used to write a script that will extract data from the OLTP database, load it into the data warehouse, and process it in the data warehouse. Provided you can program using SQL-DMO, this is the most flexible and complete way to move data into the warehouse.

There are also third-party software products developed to extract, transform, and transfer data from source data systems that generate input data to populate a Microsoft SQL Server data warehouse.


Querying Data in the Warehouse

Once you have created tables and indexes in your data warehouse, extracted, loaded, and processed data, it is time to begin analyzing the data you have stored. Microsoft offers several tools within SQL Server as well as applications external to SQL Server such as Microsoft Access, Visual Basic, Visual C++, and Internet Explorer that you can use to query your DSS database.

CUBE Operator in SQL Server

The CUBE operator is an additional switch in the GROUP BY clause in the SELECT statement.

The CUBE operator is used with an aggregate function to generate additional rows in a result set. Columns included in the GROUP BY clause are cross-referenced to produce a superset of groups. The aggregate function specified in the select_list is applied to these groups to produce summary values for the additional super-aggregate rows. The number of extra groups in the result set is determined by the number of columns included in the GROUP BY clause.

The aggregate function used in the SELECT statement is applied to the cross-referenced columns for the super-aggregate calculation. The CUBE operator can be applied to all aggregate functions, including AVG, SUM, MAX, MIN, and COUNT.

Every possible combination of the columns or expressions in the GROUP BY clause is used to produce super-aggregates. If you have n columns or expressions, there are 2 (n) -1 possible super-aggregate combinations. Mathematically, these combinations form an n-dimensional cube, which is how the operator got its name.

ROLLUP Operator in SQL Server

The ROLLUP operator is an aggregate operator that delivers aggregates and super-aggregates for elements within a GROUP BY statement. The ROLLUP operator is applicable to cumulative aggregates such as running sums or running averages. It differs from the CUBE operator only in that it is sensitive to the column's position in the GROUP BY clause. Aggregate groupings are made up of columns to the right of the current column value.

The ROLLUP operator can be used by report writers to extract statistics and summary information from result sets. The cumulative aggregates, such as running sums, can be used in reports, charts, and graphs.

The ROLLUP operator creates groupings by moving in only one direction, from right to left, along the list of columns in the GROUP BY clause. It then applies the aggregate function to these groupings. The CUBE operator creates all combinations of groupings from the list of columns in the GROUP BY clause.

SQL Workbook Publisher

SQL Workbook Publisher, included on the BackOffice Resource Kit CD-ROM, is a Microsoft Excel 97 add-in that allows users to analyze data stored in SQL Server databases on Excel spreadsheets.

SQL Workbook Publisher is a complete workgroup solution. Components are installed on the computer running Excel as well as on the computer running
SQL Server, and you can optionally install components to enable your corporate intranet for viewing saved workbooks.


Arcadia Bay Demonstration

Arcadia Bay is a demonstration, included on the BackOffice Resource Kit CD-ROM, of the data warehousing capabilities of Microsoft SQL Server. It includes a star-schema database that works with or without the Arcadia Bay Order Entry System database. It also includes an intranet-based front end so users can drill down into the data from a Web browser.

The following illustration shows the design for Arcadia Bay's star schema.

Arcadia Bay requires the following installed software:

  • Windows NT Server version 4.0 with SP2 or later
  • SQL Server version 6.5 with SP1 or later
  • Internet Information Server version 2.0
  • Internet Explorer version 3.0 or later
  • Exchange Server (optional)

The SQL Mail feature of SQL Server should be configured to log in to a predefined Exchange account, and it should be started on SQL Server.


Part 8 - Reference

The articles in Part 8 offer information you can refer to when upgrading or resizing your SQL Server database, or when writing queries to the database:

  • SQL Server Version History
  • SQL Server Code Pages
  • Estimating Database Size
  • Locking
  • Locking Behavior of Cursors


SQL Server Version History

Changes made to SQL Server from version to version may affect your existing applications. Before upgrading your server, review the list of changes.


SQL Server 6.5 and SQL Server 6.0

The following information discusses differences between SQL Server version 6.5 and SQL Server version 6.0. Selected SQL Server 6.5 behaviors can be reverted back to SQL Server 6.0 behavior by issuing the trace flag marked with an asterisk (*).


System Tables

SQL Server 6.5

Columns have been added, meanings or contents of some columns have changed, and some system tables have been added.


System Stored Procedures

SQL Server 6.5

Functionality has been expanded to include new SQL Server version 6.5 features.

The format of the output of some stored procedures has been modified to provide a clearer presentation of the information.


Installation Defaults

SQL Server 6.5

The default root directory for new installations is \Mssql.

SQL Server 6.0

The default root directory for new installations is \Sql60. (The default root directory for new installations in SQL Server 4.2x is \Sql.)


FROM Clause and Table Names (*110)

SQL Server 6.5

Errors are reported when redundant table names appear in the FROM clause. If two table names are not identical, the database IDs and table IDs are compared to determine whether or not they are the same table.

SQL Server 6.0

Redundant table names in the FROM clause are supported. SQL Server uses string comparisons alone to determine whether two table names identify the same table.


SELECT DISTINCT with ORDER BY (*204)

SQL Server 6.5

ANSI-compliant. SELECT DISTINCT queries containing sort columns not included in the original select list in the ORDER BY clause are not supported.

SQL Server 6.0

SELECT DISTINCT queries containing sort columns not included in the original select list in the ORDER BY clause are supported.


Permission to Create Foreign Key (*237)

SQL Server 6.5

ANSI-compliant. You must have REFERENCES permission on a table to create a foreign key that refers to that table.

SQL Server 6.0

You must have SELECT permission on a table to create a foreign key that refers to that table.


SELECT INTO or CREATE VIEW (*246)

SQL Server 6.5

An error occurs if no column name is given to a column created by a SELECT INTO or CREATE VIEW statement.

SQL Server 6.0

No column name need be given to a column created by a SELECT INTO or CREATE VIEW statement.


RAISERROR and @@ERROR (*2701 or SETERROR Option)

SQL Server 6.5

The RAISERROR statement sets @@ERROR to 0 if the severity is between 1 and 10 inclusive. Messages with severity levels of 10 and under are not errors, but they do provide additional information. If you set the msg_id by using the WITH SETERROR option, the RAISERROR statement assigns the msg_id to @@ERROR regardless of severity.

SQL Server 6.0

@@ERROR is set to 50,000 for messages with severity levels 10 and under.


Backup format

SQL Server 6.5

A backup created from SQL Server 6.5 cannot be loaded into SQL Server 6.0.


Startup Procedure: sp_sqlregister

SQL Server 6.5

The stored procedure sp_sqlregister is installed as a default startup procedure. At startup, sp_sqlregister gathers basic configuration information from the operating system, network, and SQL Server and then broadcasts the SQL Server's presence on the network. Any server carrying out xp_sqlinventory can collect the information into a table. The stored procedure sp_unmakestartup can be run to remove sp_sqlregister as a startup stored procedure.


Forward-only Cursors (*7502)

SQL Server 6.5

Forward-only cursors are dynamic by default, which allows faster cursor opening and allows the result set to display updates made to the underlying tables. Dynamic cursors are faster and no longer require unique indexes.


Plans for Cursors on Stored Procedures (*7502)

SQL Server 6.5

Plans for cursors are cached for some stored procedures; this provides a gain in performance for many cursor operations. However, it will also use procedure cache to hold these plans, perhaps affecting an application's caching behavior and performance.


New Service: MS DTC

SQL Server 6.5

The Microsoft Distributed Transaction Coordinator (MS DTC) provides cross-server transaction capabilities: automatic two-phase commit. Normally, the MS DTC service should not affect existing applications, other than the automatic transactional consistency, but it does require some memory and some processing time. The service can be stopped if its features are not required.


USE Statement in EXECUTE Resets on Completion

SQL Server 6.5

After executing a string that contains a USE statement, the "current database" will automatically be reset to the database that was being used before the EXECUTE. To obtain the same behavior as in SQL Server 6.0, each statement that should be executed in the used database must be executed as a string with the USE statement preceding it.

To obtain SQL Server 6.0 behavior, use this batch:

USE master
GO
DECLARE @mydb VARCHAR(30)
SELECT @mydb = 'pubs'EXECUTE('USE ' + @mydb + 'SELECT db_name()')
go

This batch carries out the SELECT in the used database, but returns to the master database upon completion.

SQL Server 6.0

The "current database" setting persists after the EXECUTE.

This batch will output pubs in 6.0; in SQL Server 6.5, it outputs master:

USE master
GO
DECLARE @mydb VARCHAR(30)
SELECT @mydb = 'pubs'
EXECUTE('USE ' + @mydb)
go
SELECT db_name()
go


JOIN Syntax and Trace Flag 204

SQL Server 6.5

Although the outer join operators *= and =* from earlier versions of SQL Server are supported, you cannot use both outer join operators and ANSI-SQL style joined tables in the same query. When trace flag 204 is enabled, only SELECT statement syntax from SQL Server versions 6.0 and earlier is permitted; joined tables, derived tables, and other ANSI features are not permitted.


Objects Created in a Transaction

SQL Server 6.5

Objects can be created within a transaction. These operations are protected by the standard transactional rules and may be committed or rolled back as necessary. However, creating an object in a transaction causes locks to be held on system tables in the database until the creating transaction commits or rolls back. Use caution when you create objects inside a transaction; this includes the creation of temporary objects in the tempdb database.


SELECT INTO

SQL Server 6.5

SELECT INTO is wrapped within a transaction. Tables created by using SELECT INTO hold to the ACID (atomicity, consistency, isolation, durability) transaction properties. This also means that system resources, such as pages, extents, and locks, are held for the duration of the SELECT INTO statement. With larger system objects, internal tasks might be blocked by other users performing SELECT INTO statements. For example, on high-activity servers, if many users run SQL Enterprise Manager to monitor system processes, they might block each other, causing a condition in which SQL Enterprise Manager appears to hang.

Upgrade to SQL Server 6.5 Service Pack 2, to ensure that you can set the SELECT INTO locking feature as you desire. Wrapping the SELECT INTO with a transaction remains the default behavior. For users wishing not to hold system catalog locks on the activity, a trace flag has been added to allow for such operations. To apply the trace flag, start the server with the -T5302 command-prompt parameter, or from within a query window, use the following commands:

dbcc traceon (3604)
go
dbcc traceon (5302)
go

When the 5302 trace flag is applied and a SELECT INTO fails, the table is still created. The locking behavior you select is applied for all databases within the server.

SQL Server 6.0

SELECT INTO is not an atomic operation.


ISQL/w Maximum Connections

SQL Server 6.5

The number of ISQL/w maximum connections on Win16 clients is affected by the Network Packet Size configuration value of SQL Server. The smaller the Network Packet Size (minimum 512 bytes), the more simultaneous connections you can make from the same DB-Library client, because the larger the network packet size, the more system resources are used on the Microsoft Windows 3.x client. If the Network Packet Size on the server side is configured to be 512, you should be able to make the same number of connections as you would in SQL Server 6.0 from the same client.


Global Variables Disallowed in CHECK and DEFAULT Constraints

SQL Server 6.5

Global variables such as @@SPID cannot be used in CHECK or DEFAULT constraints in either CREATE TABLE or ALTER TABLE statements. This has never been documented as a valid option and is now flagged as invalid syntax, producing error 112:

Variables are not allowed in the CREATE TABLE statement.

Built-in functions continue to work in constraints.


Books Online

SQL Server 6.5

SQL Server 6.5 Books Online uses the Infoview.exe program to view text.

SQL Server does not have to be installed in order to read Books Online; Books Online can be installed independently:

Create a directory C:\Sqlbks.

Copy the \Sqlbks65\Sqlbooks.* files and \I386\Infoview.exe from the CD-ROM into that directory. You will not be able to view Books Online using Msin32.exe.

Create a Program Manager item with:

  • A command prompt of C:\Sqlbks\Infoview.exe Sqlbooks.mvb.
  • A working directory of C:\Sqlbks.

SQL Server 6.0

SQL Server 6.0 Books Online uses the Msin32.exe program to view text.


Vbsql.ocx Replaces Vbsql.vbx

SQL Server 6.5

A Visual Basic version 3.0 project that uses the 16-bit DB-Library for Visual Basic, Vbsql.vbx, should be ported to the new DB-Library for Visual Basic OLE custom control, Vbsql.ocx. For more information, see "Porting an Old DB-Library for Visual Basic Project" in SQL Server 6.5 Books Online.


Graphical SHOWPLAN

SQL Server 6.5

The graphical SHOWPLAN tabs are no longer available in SQL Enterprise Manager's Query Tool and in ISQL/w.

SQL Server 6.0

Graphical SHOWPLAN tabs are available.


Extended Stored Procedures

SQL Server 6.5

All extended stored procedures written in C must be recompiled from the C source code and relinked under SQL Server 6.5 to Opends60.lib. Loopback connections are supported through the use of bound connections.

SQL Server 6.0

Loopback connections are not supported, although possible.


Variables

SQL Server 6.0

@@PROCID specifies the stored procedure ID of the currently executing procedure.


ODBC ANSI Upgrade Changes

When you upgrade from Microsoft SQL Server version 6.0 and its associated Microsoft ODBC drivers to Microsoft SQL Server 6.5 Service Pack 2 and its associated Microsoft ODBC driver, changes in behavior are introduced. Review the "Open Database Connectivity" article in Part 6, "Programming for Microsoft SQL Server." If you are using drivers other than Microsoft ODBC drivers, consult the documentation from your driver vendor.


Future Concerns

The following features, supported in SQL Server 6.5, may be discontinued in future versions as functionality is condensed into other features:

  • Browse Mode: Although SELECT FOR BROWSE is supported in SQL Server 6.5, the functionality of the FOR BROWSE clause in SELECT statements can be achieved more efficiently by using cursors.
  • Device Mirroring within SQL Server: If your installation of SQL Server is currently using SQL Server mirroring, it is recommended that you use the mirroring functionality of Microsoft Windows NT or hardware-based mirroring instead.
  • Outer Join Syntax: With SQL Server 6.5, the syntax for outer joins in a WHERE clause (*= and =*) can be replaced with the ANSI-standard join syntax in the FROM clause by using LEFT OUTER JOIN, RIGHT OUTER JOIN, and FULL OUTER JOIN.
  • Double Quoted Strings: The use of the double quotation mark should be reserved for delimited or quoted identifiers. Although the double quotation mark can still be used to delimit a character string (rather than an object name), if SET QUOTED_IDENTIFIER ON is executed, any string delimited by double quotation marks will be assumed to be an identifier.
  • Not Equal (!=): The ANSI-standard syntax for representing NOT EQUAL is < >. This should be used in place of != in all cases.
  • Null Comparison (=NULL): The ANSI standard is IS NULL and should be used in all cases. In fact, if SET ANSI_NULLS ON is in effect, "= NULL" will return FALSE in all cases, because ANSI specifies that no value (even NULL itself) is equal to NULL.
  • Trace Flags: SQL Trace should be used for monitoring the receive buffer instead of using trace flags 4030 and 4032.

    Discontinue the use of trace flag 204; the functionality will not exist in future SQL Server versions.

    Trace flags should be used to temporarily work around a problem until a permanent solution is put in place. Although the information provided by trace flags can help you diagnose problems, keep in mind that trace flags are not part of the supported feature set. This means that future compatibility or continued use is not assured.

Discontinuing the use of the following features should also be considered:

  • Segments: User-defined segments are often used to cause database objects to be placed on certain devices for performance reasons. The use of multidisk RAID devices generally will provide a greater increase in performance with a lower associated administrative cost.
  • The DB-Library Two-Phase Commit Library: The Distributed Transaction Coordinator (MS DTC) now provides this capability automatically.


SQL Server 6.0 and SQL Server 4.2x

The information below lists differences between SQL Server version 6.0 and SQL Server version 4.2x. Selected SQL Server 6.0 behaviors can be reverted back to SQL Server 4.2x behavior by the specified trace flag marked with an asterisk (*).


Default Sort Order and Default Character Set

SQL Server 6.0

Default sort order = dictionary order, case-insensitive
Default character set = ISO 8859-1 (Latin 1 or ANSI)

SQL Server 4.2x

Default sort order = binary order
Default character set = 850 multilingual


System Tables

SQL Server 6.0

New columns have been added, meanings or contents of some columns have changed, and some new system tables have been added.


System Stored Procedures and Format

SQL Server 6.0

Functionality has been expanded to include new SQL Server version 6.0 features.

The function of some stored procedures has been integrated into the server itself, as in sp_primarykey. The format of the output has been modified to provide a clearer presentation of the information.


BETWEEN

SQL Server 6.0

ANSI-compliant. When using the "z BETWEEN x AND y" comparison, x must be less than or equal to y to return any matching values of z. It acts as "z>=x AND z<=y".

SQL Server 4.2x

When using the "z BETWEEN x AND y" comparison, x and y are exchanged if x is greater than y.


LIKE with Fixed-length Character Values (*204)

SQL Server 6.0

ANSI standard. The LIKE operator treats trailing blanks as significant.

SQL Server 4.2x

The LIKE operator treats trailing blanks as insignificant.


Nonaggregate Columns (*204)

SQL Server 6.0

ANSI-compatible. Nonaggregate columns must appear in the GROUP BY clause to be in the SELECT list or in columns in the SELECT list.

SQL Server 4.2x

Nonaggregate columns not listed in the GROUP BY clause can be in the SELECT list or in columns in the SELECT list.


Nested Aggregates (*204)

SQL Server 6.0

An expression passed to an aggregate function cannot contain an aggregate or a subquery.

SQL Server 4.2x

The following nested aggregate is allowed:

select count(count(*))
   from <table>


> ALL and < ALL

SQL Server 6.0

ANSI-compatible. Queries with >ALL (greater than ALL) or <ALL (less than ALL) evaluate to true when the subquery returns no rows.

SQL Server 4.2x

Queries with >ALL (greater than ALL) or <ALL (less than ALL) evaluate to false when the subquery returns no rows.


Subqueries

SQL Server 6.0

ANSI-compliant. Test all subqueries to ensure desired results in your applications.

Examples: Subqueries that define the scope of a NOT IN WHERE clause should evaluate to UNKNOWN or FALSE for each row that returns a NULL.

Returns only those rows with valid data that is not in the subquery search condition.

Each condition is evaluated separately to provide accurate results when one or more conditions returns no results. Subqueries are evaluated first.

DISTINCT values are returned to the outer query for evaluation. Correlated subqueries that reference the same table as the outer query need to alias and properly identify each occurrence of that table.

SQL Server 4.2x

Examples: Rows with NULL entries in the evaluated column are returned as part of the NOT IN result set.

Subqueries in the WHERE clause are evaluated such that an EXISTS, IN, or ANY, when zero rows meet the request, causes the entire query to return zero rows even if the outer query used an OR for the conditions.

In correlated subqueries where duplicates exist, a query that includes aggregates and EXISTS subqueries sometimes evaluates the query incorrectly.

Evaluating a SELECT DISTINCT correlated subquery within an IN condition of the outer query causes the outer query to return no rows.


Use of Aliases

SQL Server 6.0

If you have aliased the table, you must use the alias throughout the query in place of the table name.

SQL Server 4.2x

If you have aliased the table, you don't need to use the alias throughout the query in place of the table name. This type of a query works like:

select authors.au_lname
from authors auth


## Tables and Stored Procedures

SQL Server 6.0

A table name or stored procedure name that begins with ## (two number signs) indicates that the table or stored procedure should be accessible globally. A table or stored procedure name that begins with # (one number sign) is available only to the creating connection.

SQL Server 4.2x

A table or stored procedure that begins with ## (two number signs) is available only to the creating connection.


Column Nullability

SQL Server 6.0

The server-wide column default is NOT NULL but can be overridden at the database level and at the session level. Use the sp_dboption "ANSI null default" to set the database default. Set the session level default by using the SET statement to set ANSI_Null_Dflt_On or ANSI_Null_Dflt_Off.

It is recommended that you always specify NULL or NOT NULL when creating the column.

SQL Server 4.2x

The default column nullability is NOT NULL.

It is recommended that you always specify NULL or NOT NULL when creating the column.


Stored Procedure Parameter Checking

SQL Server 6.0

Checks stored procedure calls for too many parameters or for the use of named parameters not on the parameter list.

SQL Server 4.2x

Does not check stored procedure calls for too many parameters or for the use of named parameters not on the parameter list.


Quotation Marks

SQL Server 6.0

By default, assumes a single or double quotation mark begins and ends a string. Once the SET QUOTED_IDENTIFIER ON option has been specified, assumes double quotation marks are used only as delimiters for identifiers; strings must be delimited by single quotation marks.

SQL Server 4.2x

By default, assumes a single or double quotation mark begins and ends a string.


Primary Keys and Foreign Keys

SQL Server 6.0

To use SQL Server 6.0 declarative referential integrity (DRI), use the ALTER TABLE and the CREATE TABLE statements. Use the sp_help or the sp_helpconstraint system stored procedures to view constraint information. sp_pkeys and sp_fkeys return information based on the true declarative referential integrity from the CREATE and ALTER TABLE statements.

SQL Server 4.2x

The stored procedures sp_primarykey, sp_commonkey, sp_dropkey, sp_foreignkey, sp_helpjoins, sp_helpkey, and the syskeys table are included for backward compatibility only. These procedures and the syskeys table are related to old style primary and foreign keys that do not implement referential integrity.


ODBC SQL Server Driver

SQL Server 6.0

By default, arithabort is turned on. This is designed to be consistent with the ODBC standard that states that numeric overflows and divide by zero errors are fatal. This may cause a change in some ODBC tests, because they may have been coded to the previous default behavior.

SQL Server 4.2x

By default, arithabort is turned off.


User-defined Data Type Names

SQL Server 6.0

Case-insensitive.

SQL Server 4.2x

Case-sensitive.


RAISERROR Error Numbers

SQL Server 6.0

User error numbers start at 50,000.

SQL Server 4.2x

User error numbers start at 20,000.


Dumps

SQL Server 6.0

By default, dumping to a device that already contains a dump appends the new information to the existing data. Use INIT to overwrite an existing dump. If you don't use INIT, your dump device may fill up.

SQL Server 4.2x

By default, dumping to a device that already contains a dump overwrites the existing data with the newer information.


Conditional Compilation

SQL Server 6.0

Not available. The amount of time required to compile constant expressions is evaluated in more cases than in 4.2x. Some errors may result for stored procedures that rely on the cases in which evaluation of the amount of time required to compile was not done in 4.2x.

SQL Server 4.2x

Available. The amount of time required to compile constant expressions is evaluated in many cases.


Extended Stored Procedure Creation

SQL Server 6.0

Extended stored procedures can only be created in the master database.

SQL Server 4.2x

Extended stored procedures can be created in the master database and in user databases.


DATEDIFF Function

SQL Server 6.0

DATEDIFF accurately reflects the number of "minute boundaries" from a store of 60.

SQL Server 4.2x

DATEDIFF reflects the number of "minute boundaries" from a store of 59.


Numeric Constants with Decimal

SQL Server 6.0

Numeric constants containing a decimal point are represented by numeric values.

SQL Server 4.2x

Numeric constants containing a decimal point are represented by float values.


Extended Stored Procedures

SQL Server 6.0

Recompile and link with the Opends60.lib file to use extended stored procedures.

SQL Server 4.2x

Not applicable.


Null Checks (*243)

SQL Server 6.0

Checks for the assignment of NULL to a NOT NULL column are made at run time.

SQL Server 4.2x

Checks for the assignment of NULL to a NOT NULL column are made at compile time.


Temporary tablename Lengths

SQL Server 6.0

You can code a maximum of 20 characters for a temporary #tablename; all 20 characters will be used. If you use more than 20 characters, you will receive an error message.

SQL Server 4.2x

You can code a temporary #tablename longer than 13 characters, but only the first 13 characters are used.


Null from Nested SELECT

SQL Server 6.0

The following two queries return identical results, with the inner SELECT in the first SELECT performing similarly to the outer join in the second SELECT.

use pubs
   go
   select au_id,
     (select max(title_id)
      from titleauthor ta
      where ta.au_id = au.au_id)
   from authors au
   go

   select au.au_id, max(ta.title_id)
   from authors au, titleauthor ta
   where au.au_id *= ta.au_id
   group by au.au_id
   go

SQL Server 4.2x

The first SELECT query returns fewer rows, omitting those rows in authors where the INNER SELECT returned a null.


Reserved Keywords

These are SQL Server reserved keywords. The new reserved words (identified by "reserved") can be used as identifiers with SQL Server 6.5 but can be expected to cause syntax conflicts in future versions of SQL Server. Keywords followed by a * were first used in SQL Server 6.0. Keywords followed by a ** were first used in SQL Server 6.5.

The following keywords and reserved words are checked by the Chkupg.exe utility, which checks keywords but does not change them. The second set of keywords are not checked by Chkupg.exe. Run the Chkupg.exe utility before you upgrade.

*
**

= First used in SQL Server 6.0
= First used in SQL Server 6.5

A

ABSOLUTE | ARE
ACTION (reserved) | ASSERTION (reserved)
ADD * | AT
ALLOCATE | AUTHORIZATION **

B

BOTH

C

CASCADE ** | CONNECT
CASCADED | CONNECTION
CASE | CONSTRAINT *
CAST | CONSTRAINTS
CATALOG | CORRESPONDING
CHAR_LENGTH | CROSS **
CHARACTER (reserved) | CURRENT *
CHARACTER_LENGTH | CURRENT_DATE *
CLOSE * | CURRENT_TIME *
COALESCE * | CURRENT_TIMESTAMP *
COLLATE | CURRENT_USER *
COLLATION | CURSOR *
COLUMN |

D

DATE | DESCRIPTOR
DAY | DIAGNOSTICS
DEALLOCATE * | DISCONNECT
DEFERRABLE | DISTRIBUTED
DEFERRED (reserved) | DOMAIN
DESCRIBE | DOUBLE

E

END_EXEC | EXPIREDATE (reserved)
ESCAPE ** | EXTERNAL
EXCEPTION | EXTRACT

F

FALSE | FLOPPY *
FETCH * | FOREIGN *
FILE (reserved) | FULL **
FIRST |

G

GET

GLOBAL

H

HOUR

I

IDENTITY * | INNER **
IDENTITY_INSERT * | INPUT
IDENTITYCOL * | INSENSITIVE *
IMMEDIATE (reserved) | INTERVAL
INITIALLY (reserved) | ISOLATION *

J

JOIN **

K

KEY *

L

LAST | LEVEL *
LEADING | LOCAL
LEFT ** |

M

MATCH (reserved) | MONTH
MINUTE |

N

NAMES | NEXT
NATIONAL (reserved) | NO
NATURAL | NOCHECK *
NCHAR | NULLIF *

O

OCTET_LENGTH | OPTION *
OF * | OUTER **
ONLY * | OUTPUT
OPEN * | OVERLAPS

P

PAD | PRESERVE
PARTIAL (reserved) | PRIMARY *
PIPE * | PRIOR
POSITION | PRIVILEGES **
PRECISION |

R

READ * | RESTRICT **
REFERENCES * | RETAINDAYS (reserved)
RELATIVE | RIGHT **
REPLICATION * | ROWS

S

SCHEMA ** | SIZE
SCROLL * | SOME *
SECOND | SPACE
SERIALIZABLE * | SQLSTATE
SESSION | SUM
SESSION_USER * | SYSTEM_USER *

T

THEN * | TRAILING
TIME | TRANSLATE
TIMESTAMP | TRANSLATION
TIMEZONE_HOUR | TRUE
TIMEZONE_MINUTE |

U

UNCOMMITTED * | USAGE
UNKNOWN | USER *
UPDATETEXT * | USING

V

VALUE | VOLUME (reserved)
VARYING * |

W

WHEN | WRITE
WORK ** |

Y

YEAR

Z

ZONE


Reserved Words Not Checked by Chkupg.exe

A

ALL | AS
ALTER | ASC
AND | AVG
ANY |

B

BEGIN | BROWSE
BETWEEN | BULK
BREAK | BY

C

CHECK | CONFIRM
CHECKPOINT | CONTINUE
CLUSTERED | CONTROLROW
COMMIT | CONVERT
COMMITTED | COUNT
COMPUTE | CREATE

D

DATABASE | DEFERRABLE
DBCC | DESC
DECLARE | DROP
DISK | DUMMY
DISTINCT | DUMP
DEFAULT |

E

ELSE | EXEC
END | EXECUTE
ERRLVL | EXISTS
ERROREXIT | EXIT
EXCEPT |

F

FILLFACTOR | FROM
FOR |

G

GOTO | GROUP
GRANT |

H

HAVING

HOLDLOCK

I

IF | INSERT
IN | INTERSECT
INDEX | INTO

L

LIKE | LOAD
LINENO |

M

MAX | MIRROREXIT
MIN |

N

NOCHECK | NOT
NONCLUSTERED | NULL

O

OFF | OR
OFFSETS | ORDER
ON | OVER
ONCE |

P

PERM | PROC
PERMANENT | PROCEDURE
PLAN | PROCESSEXIT
PREPARE | PUBLIC
PRINT |

R

RAISERROR | ROLLBACK
RECONFIGURE | ROWCOUNT
REPEATABLE | RULE
REVOKE |

S

SAVE | SHUTDOWN
SELECT | SOME
SET | STATISTICS
SETUSER |

T

TABLE | TRAN
TAPE | TRANSACTION
TEMP | TRIGGER
TEMPORARY | TRUNCATE
TEXTSIZE | TSEQUAL
TO |

U

UNION | UPDATE
UNIQUE | USE

V

VALUES

VIEW

W

WAITFOR

WHERE


SQL Server Code Pages

Be sure to take character conversion into account when developing applications for client sites.

A code page, also known as a character set, is a set of 256 uppercase and lowercase letters, numbers, and symbols. The printable characters of the first 128 values are the same for all character-set choices. The last 128 characters, sometimes referred to as extended characters, differ from set to set.

Note This section only discusses single-byte character set issues of the U.S., German, and French language versions of SQL Server. It does not discuss double-byte character set (DBCS) issues of the Japanese version of SQL Server.

The default for SQL Server 6.x is ISO 8859-1 (Latin 1 or ANSI), also known as code page 1252. The code page for SQL Server determines the types of characters that SQL Server recognizes in your database data and the results that SQL Server returns for queries that involve character comparisons.

In some cases, SQL Server's code page differs from the operating system's code page. Windows NT and Windows 95 operating systems have both an ANSI (American National Standards Institute) code page and an OEM (original equipment manufacturer) code page.

The ANSI and OEM code pages depend on the country settings. The following code page settings exist for Microsoft operating systems:

  • U.S. English Windows NT Server and Workstation: default ANSI code page of 1252, OEM code page of 437.
  • U.S. English Windows 95: default ANSI code page of 1252, OEM code page of 437.
  • Internally, Windows NT Console is Unicode. However, this is a special case, and any program it runs must appear to be running in an MS-DOS code page. Therefore, console applications under Windows NT effectively run the OEM code page of the computer.


ANSI/OEM Conversion

The AutoANSItoOEM entry in the Registry controls the default conversion behavior when the data is inserted or retrieved. If AutoANSItoOEM is set to ON, conversion is turned on in the following cases:

  • ANSI clients to OEM servers
  • OEM clients to ANSI servers

If AutoANSItoOEM is set to OFF, conversion is turned off for all connections.

All of the Windows-based clients, such as ISQL/w and SQL Enterprise Manager, are considered ANSI clients. Console-based applications such as the isql and bcp utilities are considered OEM clients.

A SQL Server with the default code page of 12x, for example 1252 (ISO 8859-1), is considered to be an ANSI server; with any other code page, it is considered to be an OEM server (for example, 850, 437).

Although default code page values exist for both ANSI and OEM, the client's current operating-system code page will determine conversion values when characters are translated.

Note For more information about ANSI to OEM conversion, see SQL Server 6.5 Books Online.


Turning AutoANSItoOEM On or Off

When you develop applications for client sites, taking character conversion into account is very important. Data that was perfectly legible and correct when you programmed it on your ANSI 1252 client might become gibberish when saved to a server (ANSI or OEM) and viewed on an OEM 437 client. DB-Library allows you to decide whether or not ASCII values for characters will be converted between ANSI and OEM so that characters remain intact from code page to code page.

The Registry entry AutoANSItoOEM can be turned on or off by selecting or clearing the Automatic ANSI to OEM check box in the DB Library window of the SQL Client Configuration Utility. In SQL Server 6.5, the Automatic ANSI to OEM check box is selected by default.


ODBC Clients

Because ODBC is a Windows API, ODBC clients use the ANSI 1252 code page. Any ODBC data source used to connect to a server running an ANSI 1252 code page should have the Convert OEM to ANSI characters check box activated. Any ODBC data source connecting to a server running a 437 or 850 code page should have the Convert OEM to ANSI characters check box activated.


Revealing SQL Server's Code Page

You can use the stored procedure sp_helpsort or sp_server_info or view the error log to reveal SQL Server's sort order and character set.


Checking the Validity of the Saved Data

You can use the Transact-SQL string function ASCII(char_expr) to reveal the character that is saved in the SQL Server database. You can also use the ASCII(column_name) function to reveal the ASCII value for a particular column in the database.

For example, assume you have saved the character "±" on a server with code page OEM 437. If you select this data from ISQL/w (which has a code page of ANSI 1252) when AutoANSItoOEM is on, you will see the "±" character. AutoANSItoOEM has converted the OEM 437 "±" (which has an ASCII value of 241) to the ANSI 1252 "±" (which has an ASCII value of 177). However, if you select the data from ISQL/w when AutoANSItoOEM is off, you will see the "ñ" character. AutoANSItoOEM has not converted the OEM 437 ASCII value of 241 but instead has retrieved the character for the ANSI 1252 ASCII value of 241.

Code page | Character ± | AutoANSItoOEM ON | AutoANSItoOEM OFF
OEM 437 | ASCII 241 | ± | ±
ANSI 1252 | ASCII 177 | ± | ñ (ASCII 241)

Another way to reveal the code page is to set AutoANSItoOEM to OFF and then query the data both from a Windows tool and from isql at a command prompt.


When a Character in One Code Page is Unavailable on Another

When a character in one code page is unavailable on another and the conversion occurs, the character gets converted to its closest equivalent character in the other code page. For example, ASCII 224 (a) in code page 437 is converted to ASCII 97 (a) in code page 1252 because this is the most similar character in the 1252 code page. When you convert this ANSI character back to code page 437, the result is ASCII 97 (a), because ASCII 97 (a) exists in both code pages. The original 437 character (a) is lost. This means that incorrect data will be saved in your database if the character exists in one code page but not the other, and AutoANSItoOEM is turned on.

Code page | Character a | OEM to ANSI (Conversion 1) | ANSI to OEM (Conversion 2)
OEM 437 | ASCII 224 | a | a (ASCII 97)
ANSI 1252 | Does not exist. | a (ASCII 97) | a (ASCII 97)

When you save your data on a server with a code page different from the code page that will be used by your clients, be sure to test your data for accuracy. If possible, choose characters that will convert easily between ANSI and OEM. For strategies to avoid these inaccuracies, see "Suggestions for Consistent Data" later in this article.


Entering Extended Characters with the U.S. Keyboard

Turn on Num Lock and use the number pad on the right side of the keyboard.

To enter ANSI extended characters

  • Press ALT+0, followed by the ASCII code.

To enter OEM extended characters

  • Press ALT followed by the ASCII code.

    For example, to enter a mu sign (m), press ALT and then 0181 for the ANSI 1252 extended character, or press ALT and then 230 for the OEM 437 extended character.


Changing the OEM Code Page of Windows NT and Windows 95

You can change the OEM code page by altering the value in:

HKEY_LOCAL_MACHINE
    \SYSTEM
        \CurrentControlSet
            \Control
                \Nls
                    \CodePage
                        \OEMCP

to the code page you want. The change takes effect after you restart Windows NT or Windows 95. By default, the OEM code page is set to 437.

Caution Modifications to the Registry can be risky, and should be carefully considered. In this instance, the OEM code page can be changed by changing the country settings. Additionally, it is risky changing the OEM code page without setting the related ANSI code page.


Suggestions for Consistent Data

The following suggestions will help ensure that the data stored on the SQL Server is stored in accordance with the SQL Server code page instead of the client's code page. Storing data in terms of the client's code page is most often the cause of bad data.

  • For OEM and ANSI clients, if the SQL Server is not using the ANSI code page, change the client's OEM code page to match the SQL Server code page and enable the AutoANSItoOEM conversion.
  • For OEM and ANSI clients, if the SQL Server is using the ANSI code page, enable the AutoANSItoOEM conversion.

Exceptions to the above suggestions are:

  • For the Win32 Bcp.exe client importing from an ANSI SQL Server (BCP out), change the client's code page to match the code page that the data was created with.
  • For the Win32 Bcp.exe client exporting to an ANSI SQL Server (BCP in), change the client's code page to the code page of the SQL Server that will receive the export results. For example, to export to a SQL Server with code page 1252, change the client's code page to 1252.


Estimating Database Size

Estimating database size before you create a database will help you with database planning.

When you create a database, it is important to accurately specify the amount of space to allocate for it. If you allocate too much space, you waste device space that could be used by other databases. If you allocate too little space, the database may run out of storage space. Although you will be able to easily expand the room allocated to the database at a later date, as long as there is space available on one or more devices, it is recommended that you estimate your database size before you begin.

Note Although you can perform detailed space calculations, there is still a chance that you will run out of space due to fragmentation, page splits, log overhead, and other factors. For example, in some situations log:data overhead can be 10:1. This means that updating 50 bytes of data can require 500 bytes of overhead. Space calculations can be very difficult to perform with accuracy, and it is recommended that you weigh the time cost of calculating space against the uncertainty of any benefit.

This section will show you how to:

  • Calculate the size of a table with a clustered index.
  • Calculate the size of a table with a nonclustered index.

The following examples are used:

  • Calculating the size of a 9,000,000-row table with a clustered index
  • Calculating the size of a 9,000,000-row table with a nonclustered index

Since the amount of overhead in tables that contain variable-length fields is greater than the overhead in tables containing fixed-length fields, two sets of formulas are presented in this example: one for fixed-length fields and one for variable-length fields.

To calculate the size of a database

Add the number of bytes of data and associated overhead.

Divide that number by the number of bytes available on a data page.

Each 2K data page uses 32 bytes of overhead, so there are 2016 (2048 – 32) bytes available for data on each data page. For best accuracy, round down divisions that calculate the number of rows per page, and round up divisions that calculate the number of pages.

If you are using FILLFACTOR in your CREATE INDEX statement, it will change some of the equations. For more information, see "Other Factors" later in this article. If a table includes text or image data types, use 16 bytes—the size of the text pointer that is stored in the row—as indicated in the following examples, and see "Using Average Sizes for text/image Data Pages" later in this article.

The following table shows the storage sizes for SQL Server data types.

Data type | Size
char | Defined size
varchar | Data size
binary | Defined size
varbinary | Data size
int | 4
smallint | 2
tinyint | 1
float | 8
float(b) | 4 (for precision of 1–23), 8 (for precision 24–53)
double precision | 8
real | 4
money | 8
smallmoney | 4
datetime | 8
smalldatetime | 4
bit | 1
decimal | 2–17 bytes, depending on precision
numeric | 2–17 bytes, depending on precision
text | 16 bytes + 2K per initialized column, or data size + text/image overhead, whichever is larger
image | 16 bytes + 2K per initialized column, or data size + text/image overhead, whichever is larger
timestamp | 8

Note Any columns defined to accept null values must be considered variable-length columns, since they involve the overhead or space savings associated with the variable-length columns and are stored as variable length.

The decimal and numeric data types have a maximum precision of 38. Based on the precision specified, a length is computed and used as the size of the array to store the data type. The following table shows the mapping from precision to size.

Precision | Size
0–2 | 2
3–4 | 3
5–7 | 4
8–9 | 5
10–12 | 6
13–14 | 7
15–16 | 8
17–19 | 9
20–21 | 10
22–24 | 11
25–26 | 12
27–28 | 13
29–31 | 14
32–33 | 15
34–36 | 16
37–38 | 17

All calculations in the following examples are based on the maximum size for varchar and varbinary data, the defined size of the columns. They also assume that columns were defined as NOT NULL. If you want to use average values for variable-length columns, see "Using Average Sizes for Variable Fields" later in this article.


Calculating the Size of a Table with a Clustered Index

The steps in this section demonstrate how to calculate the size of a table with a clustered index. For an example of how to use the formulas presented in this section, see "Calculating the Size of a 9,000,000-Row Table with a Clustered Index" later in this article.

Step 1: Calculate the Data Row Size

Calculation of data row size is slightly different depending on whether the row stores any variable-length columns. Use the first formula if all the columns are fixed-length and defined as NOT NULL. Use the second formula if the row contains variable-length columns or if the columns are defined as NULL.

  • For fixed-length columns, calculate:

    2 + (sum of bytes in all fixed-length columns) = Data Row Size

  • For fixed- and variable-length columns, calculate:

    2 + (sum of bytes in all fixed-length columns) + (sum of bytes in all variable-length columns) = Subtotal

    Subtotal + ((Subtotal/256) + 1) + (Number of variable-length columns + 1) + 2 = Data Row Size

The values 1 and 2 in the previous equations are overhead that SQL Server uses for internal storage.

Step 2: Calculate the Number of Data Pages

Calculate the number of data pages using these formulas:

2,016/(Data Row Size) = number of data rows per page (round down, as there are no partial rows on a page)

(number of rows)/(number of data rows per page) = number of data pages required (round up)

Step 3: Calculate the Size of Clustered Index Rows

Calculation of the size of clustered index rows depends on whether the keys are fixed- or variable-length. Use the first formula if all keys are fixed-length. Use the second formula if keys include variable-length columns.

  • For fixed-length columns, calculate:

    5 + (sum of bytes in the fixed-length index keys) = clustered index row size

  • For fixed- and variable-length columns, calculate:

    5 + (sum of bytes in the fixed-length index keys) + (sum of bytes in variable-length index keys) = Subtotal

    (Subtotal) + ((Subtotal/256) + 1) + (number of variable-length columns + 1) + 2 = clustered index row size

The values 5 and 2 in the previous equations are overhead that SQL Server uses for internal storage.

Step 4: Calculate the Number of Clustered Index Pages

After you have calculated the row size of the clustered index, you can calculate the number of pages for the clustered index using these formulas:

(2,016/clustered index row size) – 2 = number of clustered index rows per page

(number of data pages)/(number of clustered index rows per page) = number of index pages at level 0

If the result is greater than 1, repeat the following division step, using the quotient as the next dividend, until the quotient equals 1. When the quotient equals 1, you have reached the root level of the index.

(number of index pages at the last level)/(number of clustered index rows per page) = number of index pages at next level

Step 5: Calculate the Total Number of Pages

Calculate the total number of pages using this formula:

(number of data pages) + (number of index pages at level 0) + (number of index pages at next level) + (number of index pages at next level) […] = total number of data pages


Calculating the Size of a 9,000,000-Row Table with a Clustered Index

Calculating the Size of a 9,000,000-Row Table
with a Clustered Index

The following example calculates the size, in 2K pages, of the data and clustered index for a table containing:

  • 9,000,000 rows
  • Sum of bytes in fixed-length columns = 100
  • Sum of bytes in two variable-length columns = 50
  • Clustered key, fixed-length = 4 bytes

The five steps previously discussed were used to ascertain the table size.

Calculate the data row size.

4 Overhead

+ 100 Sum of bytes in all fixed-length columns

+ 50 Sum of bytes in all variable-length columns

———--

154 Subtotal

+ 1 (Subtotal / 256) + 1 (Overhead)

+ 3 Number of variable-length columns + 1

+ 2 (Overhead)

———--

160 Data row size

Calculate the number of data pages.

2,016/160 = 12 data rows per page

9,000,000/12 = 750,000 data pages

Calculate the size of clustered index rows.

5 Overhead

+ 4 Sum of bytes in the fixed-length index keys

———--

9 Clustered index row size

Calculate the number of clustered index pages.

(2,016/9) — 2 = 222 clustered index rows per page

750,000/222 = 3,378 index pages (level 0)

3,378/222 = 15 index pages (level 1)

15/222 = 1 index page (level 2)

Calculate the total number of pages.

Totals | Pages | Rows
Level 2 (root) | 1 | 15
Level 1 | 15 | 3,378
Level 0 | 3,378 | 750,000
Data | 750,000 | 9,000,000
 | ——— |
Total number of 2K pages | 753,394 |


Calculating the Size of a Table with a Nonclustered Index

The steps in this section show how to calculate the size of a table with a nonclustered index.

Step 1: Calculate the Size of the Leaf Index Row

Calculating the size of nonclustered index rows depends on whether the keys are fixed- or variable-length.

  • If all the keys are fixed-length, calculate the size of nonclustered leaf rows as follows:

    7 + (sum of fixed-length keys) = size of leaf index row

  • If the keys include variable-length columns, calculate the size of nonclustered leaf rows as follows:

    9 + (sum of length of fixed-length keys) + (sum of length of variable-length keys) + (number of variable-length keys) + 1 = Subtotal

    (Subtotal) + ((Subtotal/256) + 1) = (size of leaf index row)

The values 7 and 9 in the previous equations are overhead that SQL Server uses for internal storage.

Step 2: Calculate the Number of Leaf Pages in the Index

Calculate the number of leaf pages using these formulas:

2,016/(size of leaf index row) = number of leaf rows per page

(number of rows in table)/(number of leaf rows per page) = number of leaf pages

Step 3: Calculate the Size of the Nonleaf Rows

Calculate the size of nonleaf rows using this formula:

(size of leaf index row) + 4 = size of nonleaf row

The value 4 in the previous equation is overhead that SQL Server uses for internal storage.

Step 4: Calculate the Number of Nonleaf Pages

Calculate the number of nonleaf pages using these formulas:

(2,016/size of nonleaf row) – 2 = number of nonleaf index rows per page

(number of leaf pages/number of nonleaf index rows per page) = number of index pages at level 1

If the result is greater than 1, repeat the following division step, using the quotient as the next dividend, until the quotient is equal to 1. When the quotient is equal to 1, you have reached the root level of the index.

(number of index pages at last level)/(number of nonleaf index rows per page) = number of index pages at next level

Step 5: Calculate the Total Number of Nonleaf Index Pages

Calculate the total number of nonleaf index pages using this formula:

(number of index pages at level 0) + (number of index pages at next level) + (number of index pages at next level) + (number of index pages at next level) […] = (total number of 2K data pages used)


Calculating the Size of a 9,000,000-Row Table with a Nonclustered Index

Calculating the Size of a 9,000,000-Row Table
with a Nonclustered Index

The following example calculates the size of a nonclustered index on the 9,000,000-row table used in "Calculating the Size of a 9,000,000-Row Table with a Clustered Index," earlier in this article. There are two keys, one fixed- and one variable-length. The table contains:

  • 9,000,000 rows.
  • Sum of bytes of fixed-length columns = 100.
  • Sum of bytes of two variable-length columns = 50.
  • Nonclustered key, fixed-length = 4 bytes.
  • Nonclustered key, variable-length = 20 bytes.

The five steps previously discussed were used to ascertain the index size.

Calculate the index row size.

9 Overhead

+ 4 Sum of length of fixed-length keys

+ 20 Sum of length of variable-length keys

+ 2 Number of variable-length keys + 1

———---

35 Subtotal

+ 1 (Subtotal / 256) + 1

———---

36 Size of Leaf Index Row

Calculate the number of leaf pages in the index.

2,016/36 = 56 nonclustered leaf rows per page

9,000,000/56 = 160,715 leaf pages

Calculate the size of the nonleaf rows.

36 + 4 = 40 size of nonleaf index row

Calculate the number of nonleaf pages.

(2,016/40) — 2 = 48 nonleaf index rows per page

160,715/48 = 3,348 index pages, level 1

3,348/48 = 69 index pages, level 2

69/48 = 2 index pages, level 3

2/48 = 1 index page, level 4

Calculate the total number of nonleaf index pages.

Totals | Pages | Rows
Level 4 (root) | 1 | 2
Level 3 | 2 | 69
Level 2 | 69 | 3,348
Level 1 | 3,348 | 160,715
Level 0 (leaf) | 160,715 | 9,000,000
 | ——— |
Total number of 2K pages | 164,135 |


Other Factors

There are other factors to take into account when you calculate the database size. The FILLFACTOR affects the calculations for clustered index pages, distribution pages, and data pages, and using an average size for variable fields affects the calculations presented in the preceding examples. The following sections provide more information about these topics and calculations for using average sizes for variable fields.


Using a FILLFACTOR Value of 100 Percent

Normally, the index management process leaves room for two additional rows on each index page. When you set FILLFACTOR to 100 percent, it no longer leaves room for these rows. The only effect on these calculations is on calculating the number of clustered index pages, and calculating the number of nonleaf pages. Both of these calculations subtract 2 from the number of rows per page. When using a FILLFACTOR of 100 percent, do not subtract 2 from the number of rows per page.


Using Different FILLFACTOR Values

Other values for FILLFACTOR reduce the number of rows per page on data pages and leaf index pages. To compute the correct values when using FILLFACTOR, multiply the size of the available data page (2,016) by the FILLFACTOR. For example, if your FILLFACTOR is 75 percent, your data page would hold 1,512 bytes. Use this value in place of 2,016 in Step 2 for both clustered and nonclustered index calculations.


Using Distribution Pages

Distribution pages are created when you create an index on existing data and when you run UPDATE STATISTICS. A distribution page occupies one full data page.

The UPDATE STATISTICS statement adds one distribution page per index on which statistics have been created. If you UPDATE STATISTICS for an entire table, add one page for each index on the table. If you UPDATE STATISTICS for only one index, add 1.


Using Average Sizes for Variable Fields

The preceding calculations use the maximum size of the variable-length fields. If you know the average size of the fields, you can use this value in Steps 1 and 4 for calculating table size, and the value in Step 1 for calculating the nonclustered index size. You'll need slightly different formulas for clustered and nonclustered indexes.

For Clustered Indexes

In "Step 1: Calculate the Data Row Size," to determine the average data row size, use the sum of the average length of the variable-length columns instead of the sum of the defined length of the variable-length columns.

+ (sum of bytes in all fixed-length columns) + (sum of bytes of the average length of variable-length columns) = Subtotal

In "Step 2: Calculate the Number of Data Pages," use the average data row size from the first formula.

(average data row size) = number of data rows per page

In "Step 3: Calculate the Size of Clustered Index Rows," perform the addition twice.

  • The first time, calculate the maximum index row size, using the given formula:

    5 + (sum of bytes in the fixed-length index keys) + (sum of bytes in variable-length keys) = Subtotal

    Subtotal + ((Subtotal/256) + 1) + 2 = maximum index row size

  • The second time, calculate the average index row size, substituting the sum of the average number of bytes in the variable-length index keys for the sum of the defined number of bytes in the variable-length index keys.

In "Step 4: Calculate the Number of Clustered Index Pages," substitute the following formula for the first formula, using the two different length values you calculated in the previous equation.

(2,016 - (2 * maximum index row size))/average index row size = number of clustered index rows per page.

For Nonclustered Indexes

In "Step 1: Calculate the Size of the Leaf Index Row," perform the addition twice.

  • The first time, calculate the maximum leaf index row size, using the given formula:

    5 + (sum of bytes in the fixed-length index keys) + (sum of the average number of bytes in variable-length index keys) = Subtotal

    Subtotal + ((Subtotal/256) + 1) + 2 = maximum index row size

  • The second time, calculate the average leaf index row size, substituting the average number of bytes in the variable-length index keys for the sum of bytes in the variable-length index keys.

In "Step 2: Calculate the Number of Leaf Pages in the Index," use the average leaf index row size in the first division procedure.

2,016/(average leaf index row size) = number of leaf rows per page

In "Step 3: Calculate the Size of the Nonleaf Rows," use the average leaf index row size.

(average leaf index row) + 4 = size of nonleaf row

In "Step 4: Calculate the Number of Nonleaf Pages," substitute the following formula for the first formula, using the maximum and average row sizes calculated in Step 1.

(2,016 - (2 * maximum index row size))/average index row size = number of nonleaf index rows per page


Using Average Sizes for Very Small Rows

SQL Server can store as many as 256 data or index rows on a page. If your rows are extremely short, the minimum number of data pages are:

number of rows/256 = number of data pages required


Using Average Sizes for text/image Data Pages

Each text or image column stores a 16-byte pointer in the data row, with the data type varchar(16). Each text or image column that is initialized requires at least 2K, 1 data page, of storage space.

The text and image columns are designed to store implicit null values, meaning the text pointer in the data row remains null and no text page is initialized for the value, saving 2K of storage space.

If a text or image column is defined to allow null values and the row is created with an INSERT statement that includes NULL for the text or image column, the column is not initialized, and the storage is not allocated.

If a text or image column is changed in any way with UPDATE, including an update to a null value, then the text page is allocated. Inserts or updates that place actual data in a column initialize the page.

The text chains that store text and image data have 112 bytes of overhead per page. Use the following formula to calculate the number of text chain pages that a particular entry will use:

data length/1,800 = number of 2K pages

The result should be rounded up in all cases; for example, a data length of 1,801 bytes requires two 2K pages.


Locking

A locking system that maximizes performance is integral for faster throughput.

Locking synchronizes users' access to the database to ensure consistent data and correct query results. While one user locks an area of the database to view or change the data, the data is protected from other users trying to make changes to the same data. One user's changes are committed before another user can see or further change the data.

All modern database management systems use locks to provide concurrency in a multiuser environment. Some use page-level locks, some use row-level locks, some even allow you to specify, usually at table-creation time, which level of locking (page, row, or table) will be used for an individual table.

Dynamic Locking is a new kind of locking strategy. Rather than require the database administrator to analyze and anticipate which level of locking is best, Dynamic Locking uses the intelligence of the database engine to optimize the granularity of locks depending on the needs of the applications accessing a SQL Server database.

As Microsoft continues to increase the functionality of SQL Server, subsequent versions will build on the Dynamic Locking initiative. Insert row-level locking (IRL), available with SQL Server version 6.5, is the first step in Microsoft's Dynamic Locking strategy. The Dynamic Locking strategy includes:

  • A dynamic locking scheme that automatically optimizes the granularity of locks (row, pages, or tables).
  • Row-level locking for all types of transactions (INSERT, UPDATE, DELETE, and SELECT).
  • Mixed pages that group related rows from different tables on the same page and improve performance by reducing contention and the number of locks.

Benefits of Dynamic Locking include:

  • Locking intelligence is built into the database engine, which allows ISVs and corporate developers to focus on the development of applications and not on what locking strategies are appropriate.
  • Database administration is simplified, because table granularity does not have to be adjusted for individual tables.
  • Users of the database benefit from increased performance; SQL Server uses the least amount of system overhead per lock.


Locking in SQL Server 6.5

Microsoft SQL Server continues to support customizable locking when viewing data using SELECT. The level of visibility can be specified in the SELECT statement or with the transaction isolation level option for the entire session. The transaction isolation level can be set to achieve the following:

  • Ignore other users' locks, potentially viewing their uncommitted changes.
  • View only committed changes made by other users and only lock data that has changed but is not yet committed by this transaction.
  • Use locks to prevent other users from changing data that the SQL Server transaction has viewed until the transaction completes.

SQL Server further reduces contention by using optimistic concurrency control. With optimistic concurrency control, no locks are held on the rows used to populate a cursor. Transactions that are executing concurrently are not prevented from reading or updating these rows. When a change is made to a row through the cursor, SQL Server checks to see if the row has changed since it was read. The update only succeeds if the row has not been changed during the intervening period. Once updated, data is locked until committed. Optimistic concurrency control is ideal for client/server applications that allow users to browse data and make selective changes.

SQL Server uses the page as a unit of storage and the area protected by a lock. Page-level locks are fast when several rows are updated per page, because they use less locks and therefore less overhead. In most cases, page-level locking is adequate, although contention can occur on pages that users frequently access. Contention occasionally occurs when a particular row or group of rows is updated frequently. More often, contention occurs when rows are inserted at the end of a table. Insert row-level locking (IRL) addresses the latter by allowing multiple users to simultaneously insert new rows on the same page in the table. Microsoft plans to add row-level locking for updates and deletes in future development.

An understanding of how data and indexes are stored is required to appreciate how SQL Server implements insert row-level locking effectively.


How Data and Indexes Are Stored

Rows from a table are stored on pages. A table consists of a group of pages linked together in a chain. As a table grows, a new page is added from a pool of available pages that are randomly distributed throughout the file. Available pages are allocated from unused pages in the device or from pages that have been released because of deletions. The pages that make up the table are not in any physical order, though they have been linked together with pointers that point to the physical position of the next or previous page. The pointers of linked pages are stored in each page header, as illustrated in the following diagram.

The indexes in SQL Server are made up of pages that form a branching structure known as a B-tree. The starting page contains ranges of values within the table. Each range on the starting page branches to another page that contains a more detailed range of values in the table. In turn, these index pages branch out to more layers, which increase the number of pages in the layer and narrow the range of data on each page.

The branching index pages are called node pages. The final layer in the branching structure is called the leaf layer. In a unique, nonclustered index, the ranges on each leaf layer page point to a specific row of data in the table, and the data is stored separately from the index. In a clustered index, the leaf layer is made up of the data pages themselves, because the data is stored with the index, in the physical order specified in the index.

The following diagram illustrates the page structures of clustered and nonclustered indexes.


Contention

Contention occurs when two or more transactions try to access data on the same page at the same time and one must wait for the other to complete before it can proceed. In a real-time transaction-processing environment, contention becomes an important issue. Contention may be particularly evident when multiple users are inserting new rows, because often all the new rows are written to the last page in the table's page chain. Similar contention problems can arise when multiple users update or delete rows on the same page. This is not a frequent problem, because many applications typically access data that is randomly distributed over many pages, with only occasional contention for a single page.

As described above, a table with a clustered index contains rows stored in the index. When new rows are inserted, new pages are added to the page chain. The position of new pages depends on the key on which the clustered index was created. Consider a clustered index of a table based on the last name of a customer: as new customers are added, these rows are inserted into the page chain, occasionally splitting pages. Given a random set of new customers, the insertions will be evenly distributed throughout the page chain. The page chain grows by inserting new rows into partially filled pages and splitting pages that are full. If a page splits, changes must be made to the index layer.

In contrast to this, consider a table that has a clustered index based on a chronological column or on a monotonically increasing key, such as an identity value that increments each time a record is added, or an index based on the date and time the record is added. As new rows are inserted, they are added to the end of the page chain, and the page chain grows in one direction. And, because new pages are added to the end of the chain, the overhead of splitting pages is avoided. In a single-user environment, inserting into a table with an index based on a monotonically increasing key is more efficient than inserting into a table with an index based on a random key. The contention problem arises in multitransaction environments where each new insert must lock the last page exclusively. Other transactions must wait their turn, which causes a bottleneck (hotspot) on the last page.


High-Speed Locking and Concurrency Control

A multiuser environment must have the means to prevent concurrent transactions from interfering with each other. SQL Server employs a fast, sophisticated, automatic, and transparent locking scheme that arbitrates user requests. The process of obtaining a lock is exceptionally fast—a matter of microseconds—because lock information is stored in a memory-resident table. SQL Server employs multiple levels of locking (depending on the degree of exclusion required) and uses the least restrictive lock needed to protect data during a given operation.

SQL Server automatically acquires the necessary locks whenever a SQL statement is executed. SQL Server uses:

  • Shared locks for read-only operations. If a shared lock has been applied to a data page or pages, a second transaction can also acquire a shared lock even though the first transaction has not completed. By default, SQL Server releases shared locks as soon as the data page(s) is no longer needed.
  • Exclusive locks for write operations—UPDATE, INSERT, DELETE. When an exclusive lock is set, no other transaction can acquire a lock of any kind on the same object until SQL Server releases the original lock at the end of the transaction.
  • Update locks whenever a transaction intends to modify a page prior to a write operation. Update locks reduce contention among multiple writers.

Within SQL Server, the efficient use of automatic locking prevents destructive interference from concurrent transactions. By default, the changes made by the SQL statements only become visible to other transactions after those changes are committed.


Read Consistency

SQL Server provides both statement-level and transaction-level read consistency. This produces repeatable reads, an important feature for long running transactions with multiple queries that need to see the same image of the data throughout.

SQL Server allows applications to achieve the best balance between read consistency and concurrency by supporting configurable transaction isolation levels. Transaction isolation levels determine how transactions interact with one another, as described in the following table.

Isolation level | Description
READ UNCOMMITTED | Directs SQL Server not to issue shared locks and does not honor exclusive locks during reads. At this level, applications may read values within uncommitted transactions that might get rolled back later ("dirty reads"), and therefore should be used only by transactions that are insensitive to this behavior.
READ COMMITTED | Directs SQL Server to use shared locks while reading data (the default behavior). At this level, transactions cannot experience "dirty reads."
REPEATABLE READ | SERIALIZABLE | Guarantees that data read repeatedly within a transaction will retain the same values and that "dirty reads," nonrepeatable reads, and "phantom" values (values that are rolled back after being read) cannot occur. READ REPEATABLE and SERIALIZABLE are interchangeable.

You can optimize this behavior through configurable transaction isolation levels, which can be set globally for a session or individually for each SELECT statement.


Scalable Lock Escalation

With databases now reaching hundreds of gigabytes in size, the database management system must be capable of scaling efficiently. SQL Server employs a scalable lock escalation strategy based on a percentage of table size, avoiding premature lock escalation for large tables. For example, when a transaction is performing a scanned UPDATE, it can acquire a very large number of page locks, requiring escalation to a table-level lock at some point. Unlike some systems with a fixed escalation threshold (usually 200 pages, which would trigger a premature escalation for large tables), SQL Server allows this threshold to be configured by the DBA. The DBA might configure the threshold as a percentage of table size (20 percent, for example) or in terms of a specific number of pages. SQL Server can employ the optimal locking strategy for a table or database of any given size.


Automatic Deadlock Avoidance, Detection, and Correction

A deadlock is an example of a catch-22 situation. A deadlock occurs when two or more transactions have a lock on a separate object. Each wants to acquire a lock on the other transaction's object. When this happens, the first transaction is waiting for the second transaction to release the lock, but the second transaction will not let go until the lock on the first transaction's object is freed. At such a point, both transactions are at an impasse and can't proceed with their work. A deadlock can occur when several long-running transactions execute concurrently in the same database.

SQL Server automatically avoids the most common types of deadlocks. If a deadlock does occur, SQL Server detects and automatically resolves it by rolling back the first transaction that will break the deadlock for all other pending transactions, if there are more than two. In this way, the remaining transaction(s) obtains the needed lock and is free to continue. The application with the aborted transaction resubmits the transaction at a later time, when it is likely to proceed without incident.

SQL Server also automatically prevents lock starvation. Lock starvation occurs when read transactions can monopolize a table or page, forcing a write transaction to wait indefinitely. SQL Server prevents lock starvation by coordinating table and page accesses for read and write transactions in an intelligent way, based on a first-come, first-served strategy.


Row-level vs. Page-level Locking

Page-level locking effectively balances locking and deadlock detection overhead with transaction throughput for superior performance. Since all locks are managed in memory, lock acquisition is extremely fast. In the majority of business situations, page-level locking outperforms row-level locking, which is susceptible to excessive lock manager calls and frequent escalation to higher-level locks.

Superior Concurrency with High Performance

The real problem is not locking, but concurrency—locking is simply a means to an end. SQL Server employs advanced database techniques to provide high levels of concurrency, while preserving the performance characteristics of page-level locking. The most important of these include:

  • Optimistic concurrency control (default)
  • High granularity locking
  • Clustered indexes

Optimistic Concurrency Control

Cursors are database objects which enable applications to manipulate data by rows instead of by sets. Using cursors, multiple operations can be performed row by row against a result set with or without returning to the original table.

SQL Server provides rich, scrollable, engine-based cursors with configurable concurrency modes. SQL Server's optimistic concurrency mode allows users to browse both forward and backward through database rows, and update data without locking any of the data being modified. Instead, SQL Server uses sophisticated methods to detect whether the rows to be changed have been modified since the original retrieval. This protects applications against conflicting updates without locking large amounts of data, so decision support functions can continue to be performed.

Optimistic concurrency control works on the assumption that other transactions usually will not have changed the data being read. Since no locks are maintained on the current row(s) in the cursor, a high degree of concurrency is supported. Other transactions can freely read or write to the data. In the optimistic case, when an application performs an update through the cursor, it proceeds normally. However, if the row has been changed, SQL Server detects this and rejects the update, automatically refreshing the row buffers at the client with the new row information. The application then has the option of reissuing the update using explicit locking.

For row-at-a-time operations, SQL Server's engine-based cursors with optimistic concurrency control provide the highest level of concurrency available for decision support and data warehousing applications.

High Granularity Locking

SQL Server employs advanced strategies to improve the level of locking granularity and performance to provide greater concurrency, compared to other page-locking systems. There is now minimal extent locking during index creation or allocation of pages from an extent. Locking is eliminated entirely for databases that are in single-user mode or are defined as read-only. SQL Server employs new update locks that prevent multiple writers from trying to acquire exclusive locks at the same time. This significantly reduces deadlocks and retries, resulting in higher system throughput. Additionally, the lock manager itself has been made parallel and reentrant for better scalability on symmetric multiprocessing (SMP) platforms.

Clustered Indexes

Hot spotting is a significant problem with traditional page-level locking designs. In database terms, a hot spot occurs when inserts become concentrated on the last page in the table, thus causing a bottleneck. This normally occurs when data is not ordered. SQL Server uses clustered indexes to prevent this. In SQL Server, clustered indexes store the data in index order¾by incorporating the data pages into the B-tree structure of the index itself. Clustered indexes offer significant benefits, such as reduced disk I/O and increased performance in retrieval-intensive applications. The desired data can typically be accessed in a single disk read, where standard SQL implementations require multiple reads. Clustered indexes prevent hot spotting because row insertions are automatically spread throughout the table, overcoming a weakness of other page locking designs. To minimize page splitting during inserts, SQL Server allows the DBA to set a specific fill factor for a clustered index. The fill factor preserves and automatically maintains space in each page for new rows.


Insert Row-level Locking

With careful planning and a good understanding of the type and quantity of transactions that make up the database throughput, database designers can work around most major areas of contention. Now, with insert row-level locking (IRL), it is easier to achieve excellent performance for multiuser inserts. Insert row-level locking allows the individual rows on a page to be simultaneously locked by multiple transactions that insert new rows.

The lock manager has been enhanced to provide row-level locking for most INSERT operations. IRL improves performance in situations where access contention and hotspots, which are areas of unusually high access, occur.

Row-level locking is useful when a hotspot develops on tables structured as a sequential file. With SQL Server, hotspots can occur when records are inserted at the end of a table and one of the following conditions exists:

  • A table does not have an index.
  • A table has a nonclustered index, but no clustered index.
  • A table has a clustered index with a monotonically increasing key (for example, a clustered index on an identity column).

When concurrent users try to insert data into the table's last page and contend for exclusive page access, a hotspot results. To alleviate these performance bottlenecks, enhancements to the lock manager provide row-level concurrency for INSERT operations. Properly implemented IRL increases the speed of multiuser INSERT operations. For more information on IRL, see SQL Server 6.5 Books Online.

Note If a clustered index exists on a table, it must be a unique clustered index to take advantage of IRL. (Typically, a unique clustered index is created by default on the column or columns that form the primary key when the primary key is defined.)

The following diagrams illustrate how the type of index used on a table affects the amount of contention that occurs when new rows are inserted.

Note In these diagrams, the padlock sign represents a row-level lock from a transaction denoted by Tn.

Tables with nonclustered indexes on monotonically increasing keys experience contention at the leaf level of the index. The index benefits from insert-row level locking.

Tables without clustered indexes or with clustered indexes on monotonically increasing keys experience more contention on the last page, and therefore they benefit from insert row-level locking. This diagram represents a table with a clustered index on a monotonically increasing key.

The following diagram represents a table with a nonclustered index on a random key.

The following diagram represents a table with a clustered index on a random key.

Page-level locking is used for deletes and updates and is also used for inserts by default, unless insert row-level locking has been specified. When a transaction needs to update or delete a row on the page with a locked index row, the lock is escalated to an exclusive page-level lock.


Locking Behavior of Cursors

Transaction isolation levels and concurrency options affect the locking behavior of server cursors.

This article will clarify the effect of optimizer hints and isolation levels on the locking considerations of cursors. The nonlocking parts of optimizer hints affect the cursor behavior in the following ways:

  • INDEX = index_name—If the given index is unique, then this index will be used as the primary keyset for the given table. If the index is not unique, then this optimizer hint will be ignored.

    Note Use of this option may cause dynamic cursors to convert to keyset-based cursors if the index chosen does not match the "ORDER BY" columns in the cursor statement exactly.

  • FASTFIRSTROW—Dynamic cursors will always use this option whenever the primary keyset values chosen are from a nonclustered index. For keyset-based cursors, this option will be honored if it is used in the cursor statement; it will not be honored if it is not given.

The locking related parts of optimizer hints and isolation levels will affect cursor locking behavior as follows:

  • If there is a transaction outstanding, exclusive locks and table locks (TABLOCK and TABLOCKX) taken and maintained inside a user transaction are held as long as the transaction is open, even if the cursor closes, and are released when the transaction ends. If there are no transactions outstanding, the TABLOCKX and TABLOCK options will only have read duration; that is, the table lock will be active while the rows are being read, and released as soon as the read is complete.
  • The isolation level at the time the cursor is declared will be in effect throughout the cursor. Changes made to the isolation level after the cursor is declared will not affect the locking behavior.
  • The PAGELOCK keyword is ignored in DECLARE CURSOR statements.
  • If a certain optimizer locking hint is used for a given table in a cursor statement, it will override the isolation level and the cursor concurrency option for that table. For example, you can open a cursor with the LOCKCC option and specify the NOLOCK option on one of the tables participating in the cursor SELECT statement. This will cause that table to be read uncommitted, or with no locks, while other tables are protected by update locks.
  • No data modifications, using UPDATE, DELETE, or INSERT, can be made to tables that have the NOLOCK optimizer hint.
  • If no optimizer locking hint is used, the isolation-level locking will take effect on the cursor if the cursor is opened with OPTCC, OPTCCVAL, or READONLY concurrency options. If the cursor is opened with the LOCKCC option, this option will override isolation-level locking.
  • OPTCC, OPTVAL, and LOCKCC concurrency options are disallowed in cursors when the isolation level is 0. Also UPDLOCK and TABLOCKX keywords are disallowed as optimizer hints when at this isolation level.
  • If the isolation level is 0 during cursor declaration, ANSI cursors will be opened as READONLY. Extended procedure cursors will fail to open unless the READONLY option is specified.

Following is a detailed table of the kinds of locks taken with various hints and isolation levels. Some of the shorthand terminology is explained below:

RDL - Read locks These are shared page locks that are active while the pages are being read and released when the page read is complete.

SCR - Scroll locks These locks are taken by the cursor fetch command on pages that the rows are returned from. These locks will remain in place as long as the last fetch command has rows fetched from these pages. They will be released either when a subsequent fetch scrolls off these pages, or the cursor is closed. These locks come in two varieties of page locks: shared SCR(sh) and update SCR(up). Only the locks on the data pages will be kept; no locks on the index pages will be taken. Furthermore, if SCROLL locking is in effect on the cursor (shared or update) and there is an outstanding transaction in effect during opening of a keyset-based cursor, shared locks will be accumulated on pages generating the keyset, and these locks will be kept until the transaction ends.

XT/C Locks These page locks are taken by the cursor fetch command on pages that the rows are returned from. If a transaction is outstanding, these locks will be kept within the duration of the transaction and released when the transaction commits or rolls back. If there are no transactions, these locks will be kept as long as the cursor is open, or a new transaction is started and then ended. These locks also have shared and update varieties: XT/C(sh) and XT/C(up).

XT(tb) and XT(tbx) Shared and exclusive table locks. These locks can only be taken inside a transaction and can only live within the life of the transaction, not the cursor.

The following table clarifies in detail what kind of locks will be taken with cursors under different locking hints and optimizer levels.


Part 9 - Tools

Part 9 describes each of the tools for SQL Server shipped on the BackOffice Resource Kit CD-ROM:

  • Adduser.sql script
  • Arcadia Bay demonstration
  • DB Checker
  • Deadlock demonstration
  • Filltabl utility
  • Firstsql.cpp
  • Multiserver Excel macro
  • sp_help_set_options procedure
  • sp_help_sourcetext procedure
  • sp_drop_fkeys procedure
  • SQL Load Simulator
  • SQL Server Object Comparison tool
  • SQL Trend Analyzer
  • SQL Workbook Publisher
  • SQL-DMO code samples
  • Sqlhdtest utility

    Note Most tools are available for Intel platforms only and are available only in English.


Tools

SQL Server tools can help you integrate with other Microsoft products, and manage and troubleshoot your databases.


Adduser.sql Script

This script is used as part of the Multithreaded SQL Server demonstration in Part 6, "Programming for Microsoft SQL Server." The script creates 16 new users and grants them access to the tables in the pubs database.


Installing Adduser.sql

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Adduser.sql from the Bork\Sql\Examples directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install Adduser.sql

Get the Adduser.sql example from the Sql\Examples directory on the BackOffice Resource Kit CD-ROM.

At the command prompt, use the isql utility to run the script. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\adduser.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Adduser.sql script.


Arcadia Bay Demonstration

The Arcadia Bay demonstration on the BackOffice Resource Kit CD-ROM is a demonstration of the data warehousing capabilities of Microsoft SQL Server. It includes a star-schema database that works with or without the Arcadia Bay Order Entry System database. It also includes an intranet-based front end with which users can drill down into the database.


Installing the Arcadia Bay Demonstration

The following software must be installed and operational:

  • Microsoft Windows NT Server version 4.0 with SP2 or later
  • Microsoft SQL Server version 6.5 with SP1 or later
  • Microsoft Internet Information Server version 2.0
  • Microsoft Internet Explorer version 3.0 or later
  • Microsoft Exchange Server (optional)

The SQL Mail feature of SQL Server should be configured to log in to a predefined Exchange account, and it should be started on SQL Server.

To set up the Arcadia Bay database

From the Sql\Arcadia directory on the BackOffice Resource Kit CD-ROM, execute DWSetup on a computer running Windows NT Server.

This will create the required database, copy all of the files over to the hard disk, and set up the Web server.

Share the \Setup directory under the \Datawarehouse installation directory as Dwsetup.

In Internet Explorer, connect to http://ServerName/ExtendedDW/.

In the left pane, click the computer icon.

In the right pane, click Access Database Attributes.

Click Submit Password.

The default password is blank, so you won't need to enter a value in the field.

Enter the name of the server that houses the shared Dwsetup directory, and click Submit Change.

You can change other data warehouse system parameters as needed, clicking Submit Change to process each request. The following table contains descriptions of the parameters you can change.

Parameters | Description
SendMailActivated | One of the features of this demonstration is the ability to process very large queries using e-mail. If SQL Mail is implemented on your system, change this parameter to Yes to activate it.
FileShareServerName | In order for users to access the software components of the demonstration, you must tell the database the name of the server where the Datawarehouse\Setup directory is shared.
AdminPassword | This is the password to access the database attributes.
LastDWLoad | This is the last date that the data was moved from the order entry system to the data warehouse. It is used by the Arcadia Bay Data Transformation utility. Do not change this value unless you are sure of what you are doing.
SQLWorkbookPublisher | To implement the SQL Workbook Publisher features of the demonstration, change this value to Yes.

Additionally, several of Microsoft Corporation's data warehouse alliance partners have provided information about their respective offerings. A Yes value in the field following the company name indicates that information is included for that company.

To load the remaining software components

Click the Back button until you return to the Load Software Components/Access Database Attributes page, then click Load Software Components.

Click on Arcadia Bay Transaction Simulator and Arcadia Bay Data Transformation Utility to install the applications.


Implementing the Arcadia Bay Demonstration

The Arcadia Bay demonstration is completely implemented using Microsoft technology. Microsoft SQL Server serves as the data repository. The data is stored in a star schema and uses Active Server Pages (ASP) in combination with Microsoft Internet Explorer to drill down to the attribute sales data stored in the database. All of the operational data is stored in one database (order entry system) and the historical data (data warehouse) is stored in another.

Arcadia Bay Transaction Simulator

This application loads sales transactions into the order entry database. At the same time, it creates scenarios that demonstrate data warehousing functionality. The following scenarios are written into the application:

  • Inventory is low on the best-selling item.
  • Promotional items sell better.
  • Sales increase when the Web server goes live.
  • Differences in sales figures are attributed to employees and customers.
  • Some store locations have better sales figures than others.

To load the order entry database with sales transactions

On the Start menu, click Programs and then click Arcadia Bay Transaction Simulator.

Click Start.

By default, the application is set to automatic mode and will load two days' worth of transactions into the order entry database.

To turn off automatic mode

  • On the File menu, click Automatic.

    In manual mode, you will be queried for the baseline number of transactions to execute per day, the baseline probability for each transaction, and the begin and end dates for the run each time you execute the application.

To set program options

  • On the View menu, click Options.

You can change the program options as you see fit. The following table contains descriptions of the options you can change.

Option | Description
Reset Log Every Program Execution | If this box is checked, the log file will be reset every time the program is run.
Create Error Log | If this box is checked, a log file will be created every time the program is run. If a log file is created, you can choose between capturing database errors only or capturing all errors.
Default Time Period | This value indicates the default number of days for which the application will create transactions. In automatic mode, the application will use this value when it creates the Options window. You can override this value at that time.

To reset the order entry system

On the File menu, click Reset System.

Log on as sa if you are prompted.

Enter values for store and warehouse inventory.

If you increased the baseline number of transactions per day, increase both the store and warehouse values accordingly.

Click OK to reset all of the tables and to create an empty order entry database.

Arcadia Bay Data Transformation Utility

This application moves data from the order entry database into the data warehouse and transforms it. It is very similar in look and feel to the Arcadia Bay Transaction Simulator. In a typical scenario, this operation would occur regularly (nightly, weekly, or monthly) based on the requirements of the application.

To move and transform data

  • Start up the Arcadia Bay Data Transformation Utility. Click Start.

By default, the application is set to automatic mode and will determine the start and end dates. The start date is calculated from the last time the utility was run. The end date is calculated from the data in the order entry database. This process will last several minutes the first time you run this application as the dimension tables are constructed. Subsequent executions will be faster.

To turn off automatic mode

  • On the File menu, click Automatic.

In manual mode, you will be queried for the begin and end dates every time you execute the application. You will also be offered the option of just loading the dimension tables or just loading the fact table. It is not recommended you do this.

To set manual run options

  • On the View menu, click Options.

You can change the manual options as you see fit. The following table contains descriptions of the options you can change.

Options | Description
Log Errors to File | If this box is checked, a log file will be created every time the program is run. If a log file is created, you can choose between capturing database errors only or capturing all errors.
Reset Log File | If this box is checked, the log file will be reset every time the program is run.

To reset the data warehouse

On the File menu, click Reset Data Warehouse.

Log on as sa if you are prompted.

Click Start.

The application indicates the active connection and shows the status of that connection. It indicates the start and end dates, and the status bar illustrates the progress of data as it moves from the order entry database into the data warehouse.


DB Checker

The integrity of each database should be periodically checked using the DBCC CHECKDB and DBCC NEWALLOC statements. This should especially be performed just before a database is dumped, because some types of problems in a database affect the integrity of the dump file. The Dbchkcrs.sql and Dbchktbl.sql files are scripts that will read the sysdatabases table to get a list of the existing databases on the system, then build a script that can be used to run the DBCC integrity checks on all of the databases. Dbchkcrs.sql does this by selecting the database names into a cursor. Dbchktbl.sql is for SQL Server version 4.2 and earlier that did not support server cursors.


Installing DB Checker Examples

The files Dbchkcrs.sql and Dbchktbl.sql can be used to generate a secondary isql script that can then be used in isql to generate a check of all databases on the system. If you ran the BackOffice Resource Kit CD-ROM Setup, you can access DB Checker from the Bork\Sql\Dbcheck directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install Dbchkcrs.sql or Dbchktbl.sql

Copy either the file Dbchkcrs.sql or Dbchktbl.sql from the Sql\Dbcheck directory on the BackOffice Resource Kit CD-ROM to a directory on your computer.

Sites with SQL Server version 4.2 must use Dbchktbl.sql; all other sites should use Dbchkcrs.sql.

At the command prompt, use the isql utility to create the secondary SQL script that will actually check the integrity of the databases. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\DBChkXXX.sql /ooutfile.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Dbchkxxx.sql script.

DBChkXXX.sq

Is either Dbchkcrs.sql or Dbchktbl.sql.

/o outfile.sql

Is the name of the file isql will produce that will contain the script that checks the integrity of all the databases on the system.


Running the Integrity Checker

The Outfile.sql produced by running the Dbchkxxx.sql scripts can then be used to check the integrity of all databases in the system.

Usage

From the command prompt:

ISQL /Usa /P password /S server_name /i location\outfile.sql /o report.rpt

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the outfile.sql script.

outfile.sql

Is the name of the file that was created by running Dbchkcrs.sql or Dbchktbl.sql.

/o report.rpt

Is the name of the file isql will produce that will contain the results of the integrity checks on the databases.

Remarks

The Report.rpt file produced by the second run of isql can either be checked manually before running the dumps or can be run through a DBCC report scanner.

The Dbchkxxx.sql scripts can be customized to do further processing. One option would be to add logic to put each database into single-user or read-only mode before running the DBCC commands, and take it out of single-user or read-only mode after the checks complete. This might be desirable since the DBCC commands may report spurious errors if they are run while users are updating the database. The decision to do this must be weighed against the availability requirements of the database, and whether there is a time window during which the database can be made read-only. Another option would be to change the Dbchkxxx.sql scripts so that they actually ran the DBCC commands, rather than building a script to be run later. Another option would be to have the logic encoded in a stored procedure which could be scheduled to run at specific times using the task manager in SQL Enterprise Manager.


Deadlock Demonstration

This demonstration shows how two tasks can deadlock each other by acquiring locks on a table in the incorrect order. More importantly, it shows how they can eliminate the deadlock simply by changing the order in which they acquire locks.

The file Deadlock.sql creates tables and stored procedures to support the demonstration. A user can then run some simple queries in ISQL/w to exhibit a deadlock problem and a solution to that problem.


Installing Deadlock.sql

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Deadlock.sql from the Bork\Sql\Examples directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install Deadlock.sql

Get the Deadlock.sql script from the Sql\Examples directory on the BackOffice Resource Kit CD-ROM.

The tables and procedures used for the demonstration are installed with the script Deadlock.sql. Edit the file and change the statement to use a user database on the server:

use devcondemo1

At the command prompt, use the isql utility to run the Deadlock.sql script. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\deadlock.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Deadlock.sql script.


Running the Deadlock Demonstration

Deadlock.sql installs two tables and three procedures that easily demonstrate deadlocks when executed from separate ISQL/w sessions.

Deadlock.sql installs two tables, checking and savings, then populates them with data. Each row in the two tables has an Id column as the primary key.

The three procedures installed by Deadlock.sql take an Id and an amount as parameters. The procedures transfer the amount specified between tables for the Id specified.

  • xfer_to_savings

    This procedure is installed first. It decrements the row pointed to by the Id parameter in the checking table, then increments the Id row in the savings table. This causes it to first lock a page in the checking table, then lock a page in the savings table.

  • xfer_to_checking_1

    This procedure is installed second. It accesses the tables in reverse. It first decrements the savings table, then increments the checking table, so it first locks a page in savings and then locks a page in checking. Since these two procedures request locks on the tables in the reverse sequence, they can deadlock if they are both executed by separate tasks at the same time, where each task specifies the same Id. If this happens, Task1 will have a lock on a row in checking and be waiting for Task2 to free a lock on the page it needs in savings. Task2, meanwhile, is waiting for Task1 to free its lock on the checking table. Since both tasks are waiting for the other to free locks, they will wait forever, which is the definition of a deadlock, or fatal embrace.

  • xfer_to_checking_2

    This procedure is installed third. It shows how simple it is to prevent the deadlock. Instead of first decrementing savings and then incrementing checking, xfer_to_checking_2 does it in the same sequence used by xfer_to_savings. Since both procedures acquire locks in the same sequence, Task2 does not acquire the lock in the savings table that prevents Task1 from completing and freeing the lock it owns in the checking table that Task2 needs to complete its transaction. While Task2 is momentarily blocked by Task1, Task2 never blocks Task1. When Task1 completes and frees its lock, Task2 can then lock the same page and complete.

To run the demonstration

Connect two separate ISQL/w sessions to SQL Server and use the database containing the deadlock demo tables and procedures.

In the first ISQL/w session execute the command:

xfer_to_savings 10, 100

Within 20 seconds, in the second ISQL/w session execute:

xfer_to_checking_1 10, 50

When the 20-second interval expires, one of the tasks will fail with a deadlock error.

In the first ISQL/w session run a new xfer_to_savings:

xfer_to_savings 55, 250

In the second ISQL/w session run the following command:

xfer_to_checking_2 55,150

When the 20-second interval expires, both tasks will complete successfully.


Questions and Answers

What is a deadlock?

A deadlock, also known as a deadly embrace or fatal embrace, occurs when two tasks each own a resource the other needs, and each is waiting for the other to free the resource before proceeding. For example:

Task A locks Object X.
Task B locks Object Y.
Task A requests a lock on Object Y, locked by Task B.
Task B requests a lock on Object X, locked by Task A.

Task A is now waiting on Task B to free Object Y, but Task B will not do that until Task A frees its lock on Object X. If the two tasks were allowed to wait for each other, they would wait forever. If SQL Server detects a deadlock, it chooses one of the tasks as a victim and stops it with an error. This frees the resource locked by the victim task, allowing the other task to complete.

What should a task do when it is chosen as the deadlock victim?

When SQL Server chooses a task as a victim, it rolls back the tasks current transaction and returns a 1205 error:

Your server command (process id nn) was deadlocked with another process and has been chosen as deadlock victim. Rerun your command.

Usually, tasks getting this error should simply rerun their transaction. By the time their SQL commands are sent back to the server, the other task should have completed its transaction and freed all the locks it held.

If an application experiences high numbers of deadlocks, it it is most likely due to coding such as that shown in the combination of the xfer_to_savings and xfer_to_checking_1 procedures. You should investigate, and change the application logic to the sequence illustrated by the combination of the xfer_to_savings and xfer_to_checking_-2 procedures.


Filltabl Utility

The Filltabl is a DB-Library-based, Win32 console utility that you can use to generate a large amount of data for a table. Filltabl queries SQL Server's catalog to learn the structure of the table, generates pseudo-random data values, and inserts the data into the table by using the DB-Library bcp API. Filltabl generates enough data values to fill the table with the number of rows you request. It even populates variable-length columns, such as varchar, text, or image columns, with variable amounts of data.

Since the data values generated by Filltabl are random, duplicate values are occasionally generated, especially for numeric data types. This can prevent Filltabl from filling tables with unique indexes or constraints, especially on numeric columns.

Filltabl is provided with its source code. If you have a DB-Library development environment, you can customize Filltabl.


Installing Filltabl

If you want to run only Filltabl, you can install the Filltabl.exe file. Filltabl.exe is an Intel executable for Windows NT or Windows 95 clients. If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Filltabl from the Start menu. Otherwise, install it from the BackOffice CD-ROM.

To install Filltabl

Copy Filltabl.exe to the Windows\System (Windows 95), or the Winnt\System32 (Windows NT Server or Windows NT Workstation) directory on your client.

To customize Filltabl, for example if you are a DB-Library developer, copy Filltabl.c, Errhndl.c, and Filltabl.mak to your DB-Library development system.


Implementing Filltabl

Filltabl can be used to generate rows with random data values in a table prior to testing.

Usage

From the command prompt:

filltabl /T dbtable /N count [/U loginid] [/P password] [/S servername] [/R randomseed]

where:

/T dbtable

Is the fully qualified name of the table to fill with data. The name should be in the format of dbname.ownername.tablename.

/Ncount

Is the number of rows to be inserted.

/U loginid

Is the user login ID. Login IDs are case-sensitive.

/P password

Is a user-specified password for the loginid specified in the /U parameter.

/S servername

Specifies which SQL Server to connect to. The servername is the name of the server computer on the network. This option is required if Filltabl is executed from a remote computer on the network.

/R randomseed

A numeric value that Filltabl will pass to the C run-time function srand to adjust the generation of the pseudo-random data values.

Remarks

There should not be a blank between the command line-prompt switches and their associated parameters. For example, /N1000 is correct, while /N 1000 is not.

Filltabl will fill all columns having numeric data types with random numbers. It will fill all character, binary, text, or image columns with randomly generated characters or bit patterns. Therefore, Filltabl is a good utility for generating large amounts of data to test actions, such as timing data transfers or backup and recovery. Since the data values are so random, Filltabl is not a good tool for generating specific values for testing the logic encoded in applications, SQL commands, triggers, or stored procedures.

Filltabl uses the C run-time function rand to generate the random values it places in the rows. The rand function is called a psuedo-random generator because it does not generate completely random numbers. If you want to ensure that your applications generate unique numbers, you can call the srand function with a starting seed value before calling rand. If Filltabl is called multiple times without specifying a /R parameter, the data values generated will be reasonably random. If you want to have more random behavior from multiple runs of Filltabl, specify a different /R randomseed value on each run of the utility. If you want Filltabl to generate the same data values for multiple runs, specify the same /R randomseed parameter on each run.

Samples

To generate 1,000 rows in a user table:

filltabl /Tsadb.dbo.smalltab /N1000 /Usa /Psapwd /SMyServer

To generate 10,000 rows in a user table with a random seed:

filltabl /TMyDB.Me.MyTable /N10000 /UMyLogin /PMyPassword /SMyServer /R35960


Firstsql.cpp

This C++ code is used as part of the DB-Library demonstration in Part 6, "Programming for Microsoft SQL Server." Firstsql.cpp is a C++ piece of code that you can add as needed to your own code.


Installing Firstsql.cpp

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Firstsql.cpp from the Bork\Sql\Examples directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To Install Firstsql.cpp

Copy Firstsql.cpp to a file on a development computer that has the SQL Server Programmer's Toolkit (PTK) components installed.

Make sure the PTK files Sqlfront.h and Sqldb.h are in the compiler's include path.

Make sure the PTK file Ntwdblib.lib is in the compiler's lib path.

From the File menu in the Visual C++ Developer's Studio, click New, and then click Project Workspace.

Set Type equal to Console Application, set Platforms to Win32, fill in the appropriate project name and location, and click Create.

Click Firstsql Classes, and then click the Insert/Files Into Project menu.

The file Firstsql.cpp should be in the Directory Contents window. Select it, and then click Add.

You can view the source by double-clicking on the Firstsql.cpp icon in the Project Contents window.

Click Build (F7) to build the project.


Multiserver Excel Macro

The multiserver Excel macro Multi.xls demonstrates how SQL-DMO can be used to create a multiserver backup macro in Microsoft Excel. The macro backs up all the databases on a network to a central file share. Providing the server has been registered, the application connects to and backs up all the databases. Then, it calculates the percentage of space used and displays the results in an Excel spreadsheet. You can extend this simple example to perform complex backup strategies and chart the use of resources.


Installing Multi.xls

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Multi.xls from the Bork\Sql\Examples directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install Multi.xls

Get Multi.xls from the Sql\Examples directory on the BackOffice Resource Kit CD-ROM.

Start Excel 97.

The macro has been optimized for Excel 97.

On the File menu, click Open.

Find Multi.xls and click Open.

Click Enable Macros.


Implementing Multi.xls

You can use the macro as is, or you can expand the code to suit your needs.

To run Multi.xls

On the Tools menu in Excel 97, click Macro, and then click Macros.

On the Macros in drop-down list box, select Multi.xls, and then click Run.

To edit Multi.xls

On the Tools menu in Excel 97, click Macro, and then click Macros.

On the Macros in drop-down list box, select Multi.xls, and then click Edit.


sp_help_set_options Procedure

sp_help_set_options reports the current state (ON or OFF) of the SET options in effect for a connection. SET options are those options controlled using the Transact-SQL SET command. SQL Server version 6.5 introduced a new system variable, @@options, which reports the current state of the SET options. @@options, however, only returns an integer value, which is hard for end users to interpret. sp_help_set_options will query @@options and produce an understandable result set indicating the current state of the SET options. It can report on all the SET options, a specific option, or those SET options whose names contain a common string.

sp_help_set_options cannot be run on SQL Server versions prior to 6.5 because it depends on the @@option.

sp_help_set_options is created as a stored procedure in the master database.


Installing sp_help_set_options

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Sphsetop.sql from the Bork\Sql\Sprocs directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install sp_help_set_options

Get the Sphsetop.sql script from Sql\Sprocs directory on the BackOffice Resource Kit CD-ROM.

sp_help_set_options is installed from the script Sphsetop.sql. At the command prompt, use the isql utility to run the Sphsetop.sql script. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\sphsetop.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Sphsetop.sql script.


Implementing sp_help_set_options

Use sp_help_set_options to get an understandable listing of the current state of one or more of the current SET options.

Usage

sp_help_set_options [@SetOptNamePattern = {optname}]
[, @Action = action]
[, @ResultBits = @ScriptVar OUTPUT]

where:

optname

Is the name of the SET option to be reported. If optname is given as a Transact-SQL wildcard pattern, all options whose name matches the pattern will be reported.

Action

Is either 'display_all' or 'display_rows'. The default is 'display_rows'.

@ResultBits = @ScriptVar OUTPUT

This parameter gives a summary code of the status of the SET options found. @ScriptVar should be defined as an integer.

Remarks

If sp_help_set_options is executed with no optname, it will report the current state of all the SET options. If sp_help_set_options is executed with an optname parameter containing the name of one of the SET options, it will report the state of that option. If sp_help_set_options is executed with an optname parameter containing a LIKE wildcard pattern, it will report the state of any option whose name matches the pattern.

If sp_help_set_options is executed with an action parameter of 'display_rows' it will return only the result set indicating the state of the SET options report on in that execution. If the action parameter is set to 'display_all' it will also report a summary code indicating how many options were matched. The summary code, @ResultBits, is a bitmap whose bits are set as follows:

0x01 - optname/optpattern matched at least one row.
0x02 - optname/optpattern matched exactly one row.
0x04 - at least one matched option is ON.
0x08 - at least one matched option is different than its default.

The result set from sp_help_set_options has three columns:

  • SameAsConfig

    This reports 'same' if the option's state matches that of the current default setting for the server and 'different' if the option's state does not match the default. The default settings for a server are controlled by the SA using the sp_configure command with the 'user options' parameter.

  • SetOptionName

    This is the name of the option to which the row pertains.

  • CurrentUser

    This is the state (ON or OFF) of the option for the current connection.

Samples

To report all of the current option settings:

sp_help_set_options

To report the settings of all options whose name contains the string ANSI:

sp_help '%ANSI%'

To report the setting for the NOCOUNT option with the @ResultBit summary code:

sp_help NOCOUNT, 'display_all'

To report the settings for all options with the @ResultBit summary code:

declare @Summary int
declare @Msg char(50)
exec sp_help_set_options @Action = 'display_all',
@ResultBits = @Summary OUTPUT
select @Msg = 'Result Summary = ' + convert(char(2), @Summary)
print @Msg


sp_help_sourcetext Procedure

sp_help_sourcetext is a stored procedure that addresses formatting problems encountered with the system stored procedure sp_helptext. The source text of views, triggers, stored procedures, rules, and defaults are stored in the syscomments table. sp_helptext can be used to view that text, providing it was not saved in encrypted format. The text is stored as a series of 255-byte segments. When sp_helptext prints the source text of an object, it treats these arbitrary 255-byte boundaries as newlines. This breaks up the displayed source in ways that make it difficult to read.

sp_help_sourcetext addresses that problem by not treating the 255-byte boundaries as newlines, reproducing the original source text. sp_help_sourcetext can be used as a functional replacement for sp_helptext.

This version of sp_help_sourcetext works on SQL Server versions 4.21a and later.

sp_help_sourcetext is created as a stored procedure in the master database.


Installing sp_help_sourcetext

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Sptstxt.sql from the Bork\Sql\Sprocs directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install sp_help_sourcetext

Get the Sptstxt.sql script from the Sql\Sprocs directory on the BackOffice Resource Kit CD-ROM.

sp_help_sourcetext is installed from the script Sphstxt.sql. At the command prompt, use the isql utility to run the Sphstxt.sql script. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\sphstxt.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Sphstxt.sql script.


Implementing sp_help_sourcetext

Use sp_help_sourcetext instead of sp_helptext to get a more readable display of the source text of stored procedures, views, triggers, rules, and defaults.

Usage

sp_help_sourcetext objname

where:

objname

Specifies the object about which the definition is to be displayed. Objname is a required parameter.

Remarks

If the objname given specifies an object created with the encryption option, sp_help_sourcetext does not return a result set. If the objname given specifies an object that either does not exist or is not the type of object for which the source text is stored, sp_help_sourcetext does not return a result set. If more than one user has created an object with the same name as specified in the objname parameter, sp_help_sourcetext will return the text of the object with the smallest object ID, not all of them.

Samples

  • u To view the source of the sp_help_sourcetext system stored procedure:

sp_help_sourcetext sp_help

go


sp_drop_fkeys Procedure

The sp_drop_fkeys stored procedure can be used to drop foreign key constraints for a referenced table. The most common use is to drop all foreign key constraints referencing a table before it is dropped, because active foreign key references will prevent a drop from completing. sp_drop_fkeys cannot be used on SQL Server versions predating version 6.0 because the procedure works with the references constraint, which is part of the Declarative Referential Integrity (DRI) component introduced in version 6.0. References constraints define the foreign key relationships in a SQL Server database. sp_drop_fkeys is created as a stored procedure in the master database.


Installing sp_drop_fkeys

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access Spdropfk.sql from the Bork\Sql\Sprocs directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install sp_drop_fkeys

Get the Spdropfk.sql script from the Sql\Sprocs directory on the BackOffice Resource Kit CD-ROM.

sp_drop_fkeys is installed from the script Spdropfk.sql. At the command prompt, use the isql utility to run the Spdropfk.sql script. For example:

C:> ISQL /Usa /Ppassword /Sserver_name /ilocation\spdropfk.sql

where:

/P password

Is the password for the SA login.

/S server_name

Is the name of the server on which SQL Server resides.

/i location

Is the full path to the Spdropfk.sql script.


Implementing sp_drop_fkeys

sp_drop_fkeys can be used to drop all, or some, of the foreign keys referencing one or more tables.

Usage

sp_drop_fkeys [@parent_tb_name = prntname]
[, @child_tb_name = chldname]
[, @fk_cns_name = consname]
[,@diagnostics_option = diagopt]
[,@num_targeted_fkeys= @ScriptVar OUTPUT]

where:

prntname

Is the name of the parent table for which the foreign keys will be dropped. If prntname is a Transact-SQL wildcard pattern, the foreign keys for all tables whose names match the pattern will be dropped. Prntname is a required parameter.

chldname

Is the name of the referencing table whose references constraints will be dropped. If chldname is a Transact-SQL wildcard pattern, the references constraints referring back to prntname from all child tables whose names match the pattern will be dropped.

consname

Is the name of the references constraint to be dropped. If consname is a Transact-SQL wildcard pattern, all references constraints whose name matches the pattern will be dropped.

diagopt

Controls the production of a diagnostic report. The values are 'yes', 'no', or 'only'; 'yes' is the default if diagopt is not specified.

@num_targeted_fkeys= @ScriptVar OUTPUT

This parameter returns the number of constraints affected by each execution of sp_drop_fkeys. @ScriptVar should be declared as an integer.

Remarks

If prntname is the name of a table, then all the references constraints which refer back to that table will be dropped. If chldname or consname are also specified, then only the subset of references constraints that qualify for all three parameters will be dropped. If prntname is a LIKE wildcard pattern, all tables whose names match the pattern will have their references constraints dropped.

If chldname is the name of a table, all of its references constraints back to the table or tables named in prntname are dropped. If chldname is a LIKE wildcard pattern, all tables whose names match the pattern will have their constraints dropped.

If consname is the name of a constraint, that constraint will be dropped. If consname is a LIKE wildcard pattern, then all constraints whose names match the pattern will be dropped.

If diagopt is 'yes', all qualifying constraints are dropped and a diagnostic report indicating which constraints were dropped is produced. If diagopt is 'no', the constraints will be dropped without a report. If diagopt is 'only', then no constraints are dropped, and only the diagnostic report is produced.

Samples

To drop all the references constraints that refer back to a specific table:

sp_drop_fkeys PriTab

To drop all the references constrains on tables whose name contain a specific string and refer back to a specific parent table:

sp_drop_fkeys PriTab, '%RefTab%'

To drop a specific constraint that refers back to a specific table:

sp_drop_fkeys @parent_tb_name='PriTab', @fk_cns_name='RefCon1'

To report how many constraints would be dropped on all child tables whose names match a string, and also to retrieve the count of constraints affected:

declare @OutKeyCount int
declare @Msg char(50)
exec sp_drop_fkeys @parent_tb_name='PriTab',
@child_tb_name='RefTab%',
@diagnostics_option = 'ONLY',
@num_targeted_fkeys = @OutKeyCount OUTPUT
select @Msg = 'Output keycount = ' + convert(char(3), @OutKeyCount)
print @Msg


SQL Load Simulator

The SQL Load Simulator application enables you to simulate a large number of user connections to Microsoft SQL Server. The program is a 32-bit application and therefore requires Windows NT Server, Windows NT Workstation, or Windows 95. Although the program uses generic ODBC calls, it does not check application programming interface (API) conformance levels, so it may not work properly with other data-source types.


Installing SQL Load Simulator

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access SQL Load Simulator from the Windows Start menu. Otherwise, install SQL Load Simulator from the BackOffice Resource Kit CD-ROM.

To install SQL Load Simulator

  • Copy the LoadSim folder from the Sql directory on the BackOffice Resource Kit CD-ROM to a directory of your choice.


Implementing SQL Load Simulator

SQL Load Simulator allows you to open one or more SQL script documents and assign between 1 and 64 execution threads to each document. You will see a status table of the threads executing the script. Each row displays the status for an individual thread.

Note The status table refreshes every 10 seconds. This delay can cause the status column to be misleading.

SQL Load Simulator fetches column descriptions for each column in the result set to simulate actual result set processing. It processes each column individually, rather than fetching one or more rows into a buffer, to reduce per-thread memory requirements.

For information about the columns of the status table, see "Column Meanings" in the SQL Load Simulator Help file.

To simulate a server load

Double-click the Sqlls icon.

Enter the requested login information in the ODBC Information dialog box.

The ODBC Data Source box lists all configured data sources. To configure additional ODBC data sources, use ODBC in Control Panel.

On the File menu, click Open, and select a SQL script.

In the Script Execution Information dialog box, enter a value between 1 and 64 in the Number of threads field.

If the number of threads exceeds the number of user connections configured on the SQL Server, you will receive errors.

On the Threads menu, click Start to begin processing the SQL script.

You can simultaneously run SQL Performance Monitor to view activity on the SQL Server.

Click the traffic signal to pause or stop processing the SQL script.


SQL Server Object Comparison Tool

The SQL Server Object Comparison (SQLComp) tool is used to perform object comparisons across a subset of SQL Server object types: stored procedures, views, tables, publications, or articles. A user can compare a set of objects in a source database to a corresponding set of objects in a target database (the objects must have the same name and object type as the source and target databases), or a single source object to a target object of the same object type (the name of the source object may be different from the name of the target object in this case).

Server administrators will find this tool useful for troubleshooting system problems. Additionally, client/server application developers can use the SQL Server Object Comparison tool during development to debug and test applications written for SQL Server.

The tool supports comparisons for the following SQL Server object types:

  • Tables

    This includes a comparison of the indexes on a table, the properties on a table, the column definitions for a table, and any recordset associated with the table.

  • Column definitions

    This is the default, with options available to check indexes, properties, and data.

  • Views

    This compares the text of the source and target view, with options for comparing the view's result data, table definition, or table definition properties.

  • Stored procedures

    This verifies that the text of the source and target stored procedures is identical, ignoring the stored procedure name.

  • Databases

    This allows a user to compare a subset of objects at a source database to a set of corresponding objects at a target database. The objects are expected to have the same name and object type at the source and the target.

  • Replication objects

    When comparing publications, the tool will verify that the source tables for each article in the publication are identical to the target table at the destination database (the target database is the subscribing database and contains the destination table for its subscription to the source article). The tool will compare nonpartitioned articles, as well as vertically and/or horizontally partitioned articles, to their subscriptions at a target database.


Installing the SQL Server Object Comparison Tool

The SQL Server Object Comparison tool needs approximately 4.2 MB of free hard-drive space for file installation. The SQL Server Object Comparison tool is a 32-bit application that requires Microsoft Windows 95, Microsoft NT Server version 4.0 or Microsoft NT Workstation version 4.0. Microsoft SQL Server version 6.5 is the target server platform for comparisons. The server that will be used as the source or target of a comparison must be configured as an ODBC data source.

The following files are created in the SQL Server Object Comparison install directory when you run a comparison:

  • Machine.ini (used internally by SQL Server Object Comparison)
  • Results.log (a logging file with full logging)
  • Results.txt (a logging file containing only PASS or FAIL)

To install the SQL Server Object Comparison tool

  • Run Setup.exe from the Sql\Sqlcomp\Disk1 directory of the BackOffice Resource Kit CD-ROM.


Implementing the SQL Server Object Comparison Tool

To get started

Start SQLComp.

Configure data source names for the source and target servers.

  • To see the list of data source names, click Configure on the Server menu.
  • If you need to define a new data source name, click New DSN.

    This brings up the ODBC Data Source Administrator dialog box.

Type a login and password in the Configure Data Source Administrator dialog box, and click OK.

The program builds two lists: one of available databases at the source DSN and the other of available databases at the target DSN.

On the Compare menu, click Objects to compare two specific objects, for example two tables, or click Databases to compare two databases.

In the source column of the Compare Objects dialog box, select the database and object type to be compared.

In the target column, select the database and object type to be compared, if applicable, and then click OK.

Comparing Objects

SQLComp currently supports comparison of tables, views, and stored procedures. The Options button is available when the object type is set to Tables or Views.

Stored Procedure

When the comparison type is Stored Proc, the text of the stored procedures is compared.

Table

If the object type is Table, the minimal comparison (no options selected) will compare the column definitions for each of the table's columns. Options may be set on Table type comparisons to compare table properties, indexes, and record sets.

View

If the selected object type is View, the text of the source and target views is compared, and the column attributes for the table the view is based on are compared to the column attributes at the target table. Other Table options are also available for a view-to-view compare, such as Compare Table Properties or Compare Data (recordset data).

Comparing Databases

SQLComp allows a user to compare a subset of objects at a source database to a set of corresponding objects at a target database. The objects are expected to have the same name and object type at the source and the target. The user may provide an ignore list for each object type when comparing databases. The ignore list is a list of objects at the source database that will not be compared to a target object. The objects in the ignore list are not compared when verification is run. If no ignore lists are provided, the verification will compare all tables, views, and stored procedures in the source database to those at the target. If objects not present at the source are present at the target, the verification will ignore these objects, since verification is from all existing source objects to their corresponding object at the target.

Comparing Replication Objects

You can compare articles and you can compare publications with SQLComp.

Comparing Articles

When comparing articles, SQLComp verifies that a subscription to an article (the destination table) contains all data and structure definition that is defined at the source article for the subscription.

To compare articles

  • Select the source and target databases, then choose the source publication and article.

    The target object for the comparison is determined by the selected subscriber server and database. SQLComp determines whether or not the article is partitioned. If the article is partitioned, the source view is compared to the target table at the subscriber database. If the article is nonpartitioned, the table which the article is based upon is compared to the target table at the subscriber database.

Comparing Publications

When comparing publications, SQLComp verifies that the source tables for each article in the publication are identical to the target table at the destination database. (The target database is the subscribing database and contains the destination table for its subscription to the source article.)

The Table options are used for nonpartitioned articles. The View options are used for partitioned articles. If an article is not partitioned, the sync object is a table.

Using the Verification Operations DLL

The verification operations DLL checks that an object exists and is of the specified type.

To use the verification operations DLL (Verify.dll) in a C\C++ application or a Visual Basic application

Add Verify.lib to the link settings in the project file (.mak or .mdp).

In C\C++, include Verify.h in the project.

For a Visual Basic or MSTest application, the following structure and function must be declared in the calling application. This information is also included in Verify.h.

typedef struct

{

char szSourceServer[255];

char szTargetServer[255];

char szSourceDBName[255];

char szTargetDBName[255];

char szSourceUser[255];

char szSourcePassword[255];

char szTargetUser[255];

char szTargetPassword[255];

char szText1[255];

char szText2[255];

char szText3[255];

char szText4[255];

char szText5[255];

char szText6[255];

long lGRBIT;

short sVOType;

}VO_STRUCT;

long __stdcall ErrVerify(VO_STRUCT * pVoStruct );

Define an object of type VO_STRUCT in your application, initialize the VO_STRUCT members, and call the ErrVerify function. The return value is zero on success, nonzero on failure. For example:

// Define the object

VO_STRUCT *myVOStruct = new VO_STRUCT;

// Initialize the structure

strcpy(myVOStruct->szSourceServer, "MySourceDSN");

strcpy(myVOStruct->szTargetServer, "MyTargetDSN");

... initialize the other string members needed for this Verification Operation type

strcpy(myVOStruct->szText6, "mystring");

lGRBIT = 7; // (bitCmpData | bitCmpTableIndexs | bitCmpTableProp)

sVOType = 301; // compare two tables

// Call the ErrVerify function:

if (ErrVerify(pVoStruct) )

{

;// failure handling statements

}

These are the values defined for the lGRBIT parameter:

// Compare record sets for a table or a view

const long bitCmpData = 0x00000001;

// Compare table index properties and properties of fields defined

// for the index

const long bitCmpTableIndxs = 0x00000002;

// Compare table properties and column properties on a table

const long bitCmpTableProp = 0x00000004;

// Full object comparison, all options ON

const long bitCmpAll = 0x0000FFFF;

These are the defined Verification Operation "types", that are entered through the sVOType member of the VO_STRUCT object:

const short TABLETOTABLE = 301; // Compare two tables or two

// nonpartitioned articles

const short VIEWTOTABLE = 302; // Compare a partitioned article

// to a subscription

const short STORED_PROC = 303; // Compare two stored procedures

const short VIEW = 306; // Compare two views

const short COMPDB = 307; // Compare two databases - not

// yet implemented

The following tables contain brief definitions of the VO_STRUCT parameters for the various comparison types:

  • TABLETOTABLE
  • VIEWTOTABLE
  • VIEW
  • STORED_PROC
  • COMPDB

TABLETOTABLE

VO_STRUCT parameter | Definition
szSourceServer | Source DSN
szTargetServer | Target DSN
szSourceUser | Source login
szSourcePassword | Source login password
szTargetUser | Target login
szTargetPassword | Target login password
szSourceDBName | Source database name
szTargetDBName | Target database name
szText1 | Source table name; for a nonpartitioned article. This is the table the article is based upon.
SzText2 | Target table name; for a subscription. This is the subscriber database's destination table.
LGRBIT | Grbit for options
sVOType | == VO_TBLTBL

VIEWTOTABLE

VO_STRUCT parameter | Definition
szSourceServer | Source DSN
szTargetServer | Target DSN
szSourceUser | Source login
szSourcePassword | Source login password
szTargetUser | Target login
szTargetPassword | Target login password
szSourceDBName | Source database name
szTargetDBName | Target database name
szText1 | Publication name
szText2 | Article name. Use VIEWTOTABLE if the article is partitioned, otherwise call TABLETOTABLE using source and destination table names.
szText3 | Destination table name in subscription database
lGRBIT | Grbit for options
sVOType | == VIEWTOTABLE

VIEW

VO_STRUCT parameter | Definition
szSourceServer | Source DSN
szTargetServer | Target DSN
szSourceUser | Source login
szSourcePassword | Source login password
szTargetUser | Target login
szTargetPassword | Target login password
szSourceDBName | Source database name
szTargetDBName | Target database name
szText1 | Source View
szText2 | Target View
lGRBIT | Grbit for options
sVOType | == VIEW

STORED_PROC

VO_STRUCT parameter | Definition
szSourceServer | Source DSN
szTargetServer | Target DSN
szSourceUser | Source login
szSourcePassword | Source login password
szTargetUser | Target login
szTargetPassword | Target login password
szSourceDBName | Source database name
szTargetDBName | Target database name
szText1 | Source SP name
szText2 | Target SP name
sVOType | == STORED_PROC

COMPDB

VO_STRUCT parameter | Definition
szSourceServer | Source DSN
szTargetServer | Target DSN
szSourceUser | Source login
szSourcePassword | Source login password
szTargetUser | Target login
szTargetPassword | Target login password
szSourceDBName | Source database name
szTargetDBName | Target database name
szText1 | Table Ignore List
szText2 | View Ignore List
szText3 | Stored Procedure Ignore List
lGRBIT | Grbit for options
sVOType | == COMPDB


SQL Trend Analyzer

SQL Trend Analyzer is a tool designed to automatically collect, store, and analyze historical SQL Server performance information obtained from SQL Trace. This data can be used for performance forecasting, performance analysis, capacity planning, statistical trend analysis, and so on. The data can also be combined with other performance data obtained from tools such as Windows NT Performance Monitor to identify causes of macroscopic performance bottlenecks, such as saturated I/O subsystems, paging, or saturated CPUs.

SQL Trend Analyzer works by collecting SQL Server command information on a specified server, importing this data into a SQL database, and then summarizing this data into useful information. There are three main components to SQL Trend Analyzer:

  • Setup.cmd (the setup and startup script)
  • Import.cmd (the collection and summarization script)
  • SQL Trend Reports97.xls (Visual Basic for Applications macros for front-end reporting and analysis)


Installing SQL Trend Analyzer

The following table lists hardware and software requirements for SQL Trend Analyzer.

Component | Server | Client
Processor | Intel 486 or higher | Intel 486 or higher
Memory and disk space | 32 MB RAM or higher 50 MB free drive space or higher | 24 MB RAM or higher
Operating system | Microsoft Windows NT Server or Windows NT Workstation, version 3.51 or later | Windows NT Server or Windows NT Workstation, version 3.51 or later
Software | Microsoft SQL Server, version 6.5 or later | Excel 97 ODBC, version 3.0.23.1 or later ODBC SQL Server Driver, version 2.65.0213 or later
Other | A SQL file named Dataname (for example, Data1) of 20 MB or more A SQL file named Logsname (for example, Logs1) of 5 MB or more |

Note The client setup portion of SQL Trend Analyzer will not work on
Windows 95.

To install SQL Trend Analyzer

From the command prompt, go to the Sql\Sqltrend directory on the BackOffice Resource Kit CD-ROM.

Run the following command:

setup server,sa_password,'path of collection file'

For example:

setup clown,red,'c:\temp'

This will install and start SQL Trend Analyzer on the server Clown (SA password "red") and will collect information, storing it in the temp directory.

If the server has no SA password, substitute two double quotes ("") for the SA password. Also, make sure that the directory path is enclosed in single quotes. The command will look like this:

setup clown,"",'c:\temp'

Note To verify that SQL Trend Analyzer is collecting data, look in the collection file directory for a file of the form SQL Trace current date.log. This file should be increasing in size as you click Refresh, provided that there is SQL Server activity.


Importing and Summarizing SQL Trend Analyzer Data

To import and summarize SQL Trend Analyzer information for reporting

From the command prompt, go to the Sql\Sqltrend directory on the BackOffice Resource Kit CD-ROM.

Run the following command:

import server,sa_password

For example:

import clown,red

This will stop SQL Trend Analyzer data collection on the server Clown (SA password "red"), import the data from the collection file directory into SQL Server, and summarize the data.

Note SQL Trend Analyzer will remember the path that contains the collection data.


Stopping SQL Trend Analyzer Data Collection

To stop SQL Trend Analyzer data collection

From the command prompt, go to the Sql\Sqltrend directory on the BackOffice Resource Kit CD-ROM.

Run the following command:

stopsqltrend server,sa_password

For example:

stopsqltrend clown,red

This will stop SQL Trend Analyzer data collection on the server Clown (SA password "red").


Restarting SQL Trend Analyzer Data Collection

To restart SQL Trend Analyzer data collection

From the command prompt, go to the Sql\Sqltrend directory on the BackOffice Resource Kit CD-ROM.

Run the following command:

startsqltrend server,sa_password,'path of collection file'

For example:

startsqltrend clown,red,'c:\temp'

This will restart SQL Trend Analyzer data collection on the server Clown (SA password "red") and collect data in the temp directory.


Reporting SQL Trend Analyzer Information

To open the SQL Trend Analyzer reporting module

In the Sql\Sqltrend directory on the BackOffice Resource Kit CD-ROM, open the Excel file SQL Trend Reports 97.

Click the button of the report that you want to view and choose a SQL Server that has had SQL Trend Analyzer information imported.

Click the Main tab, click another report button, and choose a SQL Server to view another report from another SQL Server that has had SQL Trend Analyzer run on it.

The reports available in SQL Trend Analyzer are:

  • Application Usage Pie Chart

    This report will construct a pie chart of the five applications using the highest CPU, command, duration, distinct_user, or I/O on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU applications. The output will look similar to the following:

Note To view the highest I/O, duration, command, or other applications, simply hide all columns but the one that you want to report on.

  • User Usage Pie Chart

    This report will construct a pie chart of the five users using the highest CPU, command, duration, or I/O on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU users. The output will look similar to the following:

Note To view the highest I/O, duration, command, or other applications, simply hide all columns but the one that you want to report on.

  • Command Usage Pie Chart

    This report will construct a pie chart of the five commands using the highest CPU, command, duration, or I/O on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU commands. The output will look similar to the following:

Note To view the highest I/O, duration, command, or other applications, simply hide all columns but the one that you want to report on.

  • Summary by Minute

    This report will construct a graph by minute of SQL Server vital signs, including CPU utilization in milliseconds, I/Os, distinct users, duration per command in milliseconds, and commands on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU commands. The output will look similar to the following:

It is sometimes helpful to add another x-axis for certain lines such as the duration-per-command line. To do this, double-click the line you want, click the Axis tab, and then click Secondary axis. It can also be helpful to hide all the lines you don't want to establish a correlation between. For example, if you want to see the relationship between CPU and distinct users, hide all columns but those.

Note This data can be especially useful when combined with data from Windows NT Performance Monitor. For example, if Performance Monitor indicates high CPU utilization, minute summary can determine how many milliseconds of CPU are being used by SQL Server, and whether this is related to response time (duration per command). If it is, the Command Usage Pie Chart can be used to determine the stored procedures that are consuming most of the CPU.

  • Summary by 10 Minutes

    This report will construct a graph by 10-minute intervals of SQL Server vital signs, including CPU utilization in milliseconds, I/Os, distinct users, duration per command in milliseconds, and commands on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU commands. The output will look similar to the following:

  • Summary by Hour

    This report will construct a graph by hour of SQL Server vital signs, including CPU utilization in milliseconds, I/Os, distinct users, duration per command in milliseconds, and commands on SQL Server while the SQL Trend Analyzer collector was running. It will default to the highest CPU commands. The output will look similar to the following:


SQL Workbook Publisher

SQL Workbook Publisher is a Microsoft Excel 97 add-in that allows users to easily analyze data stored in Microsoft SQL Server databases. Users create workbooks that can be populated with data from SQL Server databases. SQL Workbook Publisher enables these workbooks to be saved to SQL Server databases, where they can be shared by many people within an organization. With a few mouse clicks, users can obtain data stored in a SQL Server database in a formatted Excel workbook.

SQL Workbook Publisher offers tangible benefits to every information professional in your organization:

  • Database performance can be increased by optimizing queries for frequently requested Microsoft Excel workbooks.
  • Workbooks created and maintained by a few individuals can be viewed by many, reducing work redundancies.
  • Workbooks can be viewed in Excel or on your intranet.
  • Structured Query Language (SQL) is made friendlier because queries can be written and workbooks can be edited in Excel.

SQL Workbook Publisher components can be installed on computers running Windows NT Server, Windows 95, or Windows NT Workstation. SQL Workbook Publisher has the following installation options:

  • Server
  • Client
  • Intranet (optional)

If a computer running Windows NT Server has SQL Server 6.5 installed, it can be used as a SQL Workbook Publisher server. When you run the Transact-SQL script that installs SQL Workbook Publisher on a computer running SQL Server, 3 tables and 14 stored procedures are installed in the SQL Server database you specify. This database also stores the Excel workbooks. Before Excel workbooks can be stored in a particular database, you must install SQL Workbook Publisher in that database. SQL Workbook Publisher can be installed in one or more databases residing on one or more servers.

A computer running Windows 95, Windows NT Server, or Windows NT Workstation must have Excel 97 installed to be a client of the SQL Workbook Publisher server. You can choose between two client installations: the Publisher and the Viewer. With the Publisher installation, you can create, edit, and view Excel workbooks. The Viewer installation allows you to only view Excel workbooks.

When the Viewer is installed on Windows 95 or Windows NT clients, only the Open from SQL Server command is added to the File menu. If the Publisher is installed on Windows 95 or Windows NT clients, three new commands are added to the File menu: Open from SQL Server, Save to SQL Server, and Save As to SQL Server.

You can also install SQL Workbook Publisher on your Microsoft Internet Information Server to enable users to browse workbooks saved on SQL Server from your corporate intranet. With Microsoft Internet Explorer, users can view existing workbooks saved on one or more SQL Workbook Publisher–enabled servers, much like they can with the Viewer installation.


System Requirements

The following table lists hardware and software requirements for SQL Workbook Publisher.

Component | Server | Client
Processor | Intel 486 or higher | Intel 486 or higher
Memory and disk space | Depends on database size | 16 MB RAM or higher 1.5 MB hard disk or higher
Operating system | Microsoft Windows NT Server, version 3.51 or later | Microsoft Windows 95 or Windows NT, version 3.51 with SP5 or later
Software | Microsoft SQL Server, version 6.5 or later Optional: On the same server or a different server, Microsoft Internet Information Server, version 2.0 or later | Microsoft Excel 97 or later Optional: Microsoft Internet Explorer, version 3.0 or later


Security Issues

In a client/server relationship, multiple clients and servers communicate across one or more linked and shared networks. SQL Server's security system prevents unauthorized clients from gaining access over shared networks to data stored on SQL Servers.

SQL Server allows the system or database administrator to specify the clients that can log in to the server. The three SQL Server security modes are:

  • Standard security

    SQL Server prompts the client for a username and password each time a connection is requested. Trusted connections are also supported by this mode.

  • Integrated security

    SQL Server obtains the information from the Windows NT security system, removing the need for additional logins. Clients that connect in this mode are said to have "trusted connections."

  • Mixed security

    SQL Server also allows a combination of security methods.

The SQL Server default is standard security mode. Excel clients can connect to SQL Server with a trusted or standard connection. If you decide to implement SQL Workbook Publisher's intranet component, the SQL Server security mode must be set to mixed or standard. If you do not implement SQL Workbook Publisher's intranet component, you can use whichever security mode you think is appropriate for your needs.

Note Your users will receive the following message if your security parameters have been improperly configured or you haven't given them access permissions: Unable to connect to specified server.


Tables Created by SQL Workbook Publisher

The Transact-SQL script Sqlwpub.sql installs the tables in a specified SQL Server database.

Table | Columns | Description
SWPWorkbookFolder | FolderID | Identification number
 | FolderPath | Path
 | FolderName | Name of workbook folder
SWPWorkbook | WorkbookID | Identification number
 | FolderID | Folder that corresponds to workbook
 | Name | Name of workbook
 | Description | Description
 | Workbook | Workbook binary large object (BLOB)
 | Owner | Owner of workbook
 | LastModified | Date last modified
 | Protection | Whether workbook is public or private
SWPWorkbookSQL | SQLID | Identification number
 | WorkbookID | Workbook that corresponds to query
 | Type | Format of Excel workbook: pivot table or worksheet
 | DSN | ODBC data source name information associated with the server
 | SQL | Transact-SQL script
 | Sheet | Location of sheet in Excel workbook
 | Location | Cell location of data in Excel sheet
 | LastModified | Date last modified


Stored Procedures Installed with SQL Workbook Publisher

The Transact-SQL script Sqlwpub.sql installs the following stored procedures in a selected SQL Server database.

Stored procedure | Function |  | Used by
sp_SWPAdminDeleteFolder | Deletes the selected folder and all folders and workbooks stored within the folder. This overrides the SQL Workbook Publisher parent-child rule. |  | ISQL/w
sp_SWPCopyWorkbook | Copies the selected workbook from one folder to another. |  | SQL Workbook Publisher
sp_SWPCreateFolder | Creates a folder. |  | SQL Workbook Publisher
sp_SWPCreateWorkbook | Creates a SQL Workbook Publisher workbook. |  | SQL Workbook Publisher Wizard
sp_SWPDeleteFolder | Deletes the selected folder. |  | SQL Workbook Publisher
sp_SWPDeleteWorkbook | Deletes the selected workbook. |  | SQL Workbook Publisher
sp_SWPGetFolders | Displays all folders available in a selected database or in another folder. |  | SQL Workbook Publisher
sp_SWPGetWorkbookInfo | Displays the properties of one or more selected workbooks. |  | SQL Workbook Publisher
sp_SWPGetWorkbook | Displays all workbooks available in a selected folder. |  | SQL Workbook Publisher
sp_SWPGetUserName | Returns the username of the user logged in to SQL Server to verify whether the current user owns the workbook to be saved. |  | MS Query SQL Server
sp_SWPIsDuplicateFolder | Checks the FolderName column in the SWPWorkbookFolder table for duplicate names. Causes an error message to be displayed if a particular name already exists for a folder. |  | SQL Workbook Publisher
sp_SWPIsDuplicateWorkbook | Checks the Name column in the SWPWorkbook table for duplicate names. Causes an error message to be displayed if a particular name already exists for a folder. |  | SQL Workbook Publisher
sp_SWPMoveWorkbook |  | Moves the selected workbook from one folder to another. | SQL Workbook Publisher
sp_SWPRenameFolder |  | Stores a new folder name in the SQL Server database. | SQL Workbook Publisher
sp_SWPRenameWorkbook |  | Stores a new workbook name in the SQL Server database. | SQL Workbook Publisher
sp_SWPSaveSQL |  | Stores a SQL query in the SQL Server database. | SQL Workbook Publisher Wizard
sp_SWPUpdateFolderPath |  | Updates the FolderPath column of all subfolders when a folder is renamed. | SQL Workbook Publisher
sp_SWPUpdateWorkbookProperties |  | Refreshes the properties of a specified workbook. | SQL Workbook Publisher


SQL Workbook Publisher SQL Script

The Transact-SQL script included with SQL Workbook Publisher, Sqlwpub.sql, must be installed in each SQL Server database that will be used to retrieve information and publish workbooks. Workbooks must be published to the same database that stores the data used to create the workbook. Data can be retrieved from only one database per workbook with a SELECT statement. You can use stored procedures in scripts to access data from multiple databases and servers if the stored procedures are registered in the databases they will be accessing.


Installing SQL Workbook Publisher

SQL Workbook Publisher can be installed on computers running Windows NT Server, Windows 95, or Windows NT Workstation.

To Install SQL Workbook Publisher on a SQL Server

This task is for database administrators.

Before installing SQL Workbook Publisher on your SQL Server, you must copy Sqlwpub.sql from the Sql\Swp\Excel97 directory on the BackOffice Resource Kit CD-ROM to your Windows NT Server computer.

Caution It is recommended that you execute Sqlwpub.sql in the pubs database to familiarize yourself with its functionality. If you run Sqlwpub.sql in the model database, all future databases, including tempdb each time SQL Server is started, will be populated with the SQL Workbook Publisher tables and stored procedures. Additionally, for Sqlwpub.sql to execute properly in the model database, model will need an additional 1 MB of space.

If you increase the size of the model database, thereby increasing the size of tempdb each time SQL Server is started, be sure you have enough disk space in the master database to accommodate it. If you do not have enough disk space, you will need to expand the master database, otherwise the next SQL Server startup will fail.

Start Microsoft ISQL/w.

In the Server box, select the server on which you want to install SQL Workbook Publisher.

In the Login ID box, type a valid login identification for the SQL Server. Be sure the login identification allows database owner access to the database.

In the Password box, type the password for the login ID, and click Connect.

In the DB box of the Query window, select the database on which you want to install SQL Workbook Publisher. This database stores the data that users will query to create Microsoft Excel workbooks. It is also where users eventually will store new workbooks.

Click Load SQL Script, locate Sqlwpub.sql, and select it.

After the Sqlwpub.sql script appears in the query window, click Execute Query.

Repeat steps 5 through 7 for each database on the server that you want to use for SQL Workbook Publisher.

You can quit Microsoft ISQL/w after all SQL Workbook Publisher objects have been installed.

To Install SQL Workbook Publisher on an Excel Client

This task is for Excel users.

There are two SQL Workbook Publisher client installations: the Publisher and the Viewer. The Publisher installation is for users who create, edit, and view workbooks. The Viewer installation is for users who only view existing workbooks.

Double-click the Setup.exe icon for either Publisher or Viewer in the Sql\Swp\Excel97 directory on the BackOffice Resource Kit CD-ROM. SQL Workbook Publisher will be activated the next time the user starts Excel. After installation, the following commands are available on the File menu:

  • Open from SQL Server (Viewer and Publisher)
  • Save to SQL Server (Publisher only)
  • Save As to SQL Server (Publisher only)

Caution Do not install both the Publisher and the Viewer on the same computer. If you have one of them installed and would like to install the other, you must first remove the existing SQL Workbook Publisher application from your computer using Add/Remove Programs in Control Panel.

To Install SQL Workbook Publisher for Viewing Workbooks on an Intranet

This task is for Webmasters.

If you plan to prepare Excel workbooks to be viewed on an intranet, you must install the following:

  • Microsoft Internet Information Server (IIS) on a Windows NT Server. (The server can be the same as or different from the one on which the workbooks are stored.)
  • Microsoft Internet Explorer, or another Web browser, on a Windows NT Server, Windows NT Workstation, or a Windows 95 client.

You must perform the following tasks to enable your intranet for viewing Excel workbooks:

Install SQL Workbook Publisher on the IIS.

Prepare the IIS for viewing Excel workbooks.

Task 1: Install SQL Workbook Publisher on the IIS

Each IIS needs its own set of SQL Workbook Publisher scripts. Perform these steps for each IIS you want to enable for SQL Workbook Publisher.

Find the IIS directory.

The directory default name is the Inetsrv folder on Windows NT Server 3.51 and the InetPub folder on Windows NT Server 4.0. By default, at least two folders will appear in this directory: Scripts and Wwwroot.

Create a new directory in Scripts called Sqlwpub.

Create a new directory in Wwwroot called Sqlwpub.

Copy the four files from the Sql\Swp\Intranet\Scripts directory on the BackOffice Resource Kit CD-ROM (Folders.htx, Folders.idc, Database.htx, and Database.idc) into Scripts\Sqlwpub.

Copy the Help folder and its contents from the Sql\Swp\Intranet\Wwwroot directory on the BackOffice Resource Kit CD-ROM into Wwwroot\Sqlwpub.

Copy the three graphics files from the Sql\Swp\Intranet\Wwwroot directory on the BackOffice Resource Kit CD-ROM (Folder.gif, Workbook.gif, and Question.gif) into Wwwroot\Sqlwpub.

Task 2: Prepare IIS for Viewing

Each database requires its own system data source name (DSN), set of database files, and set of folder files. Perform these subtasks for each database.

Subtask 1: Create a system DSN

On the Windows Start menu, point to Settings, and click Control Panel.

In Control Panel, double-click ODBC.

In the Data Sources dialog box, click System DSN.

In the System Data Sources dialog box, click Add.

In the Add Data Source dialog box, select SQL Server, and click OK.

In the ODBC SQL Server Setup dialog box, type a unique name in the Data Source Name (DSN) box (for example, DSN1).

Enter the name of the SQL Server that stores the SQL Workbook Publisher database in the Server box, and click Options.

Type the name of the database that stores the data for the workbooks (for example, pubs).

Verify that Trusted Connection (Windows NT Server 3.51) or Use Trusted Connection (Windows NT Server 4.0) is not selected, and click OK.

Subtask 2: Edit database files

Copy and rename Database.idc to the name of the database you'll be referencing (for example, pubs.idc).

Copy and rename Database.htx to a name matching the database.idc name (for example, pubs.htx).

Subtask 3: Edit folder files

Copy and rename folders.idc to an original name (for example, folders1.idc).

Copy and rename folders.htx to a name matching the folders.idc name (for example, folders1.htx).

In the renamed database.htx file, search for "folders.idc" and change it to the renamed folders.idc.

In the renamed folders.htx file, edit the Visual Basic script. The script will look like this:

Sub LoadWorkbookID(WorkbookID)

cSQLWorkbookPublisher.LoadWorkbook WorkbookID, "<%Server%>", "pubs", #

End Sub

where:

pubs should be changed to the name of the database. (It is suggested you use the pubs database to understand the functionality of SQL Workbook Publisher before implementing it fully on your production servers.)

# indicates the security mode the client uses to connect to SQL Server. 1 indicates standard security. 2 indicates integrated security.

In the renamed folders.idc file, edit the following lines:

  • "Datasource" should be the data source name you entered in Subtask 1, Step 6.
  • "Username" should be the login ID used by IDC to connect to the server.
  • "Template" should be the renamed folders.htx file that corresponds to this renamed folders.idc file.

Instruct users to view workbooks at: http://server/scripts/sqlwpub/database.idc

where:

database.idc has been changed to the name of your database. If you have multiple databases and servers, use Template.htm included in the Sql\Swp\Intranet directory on the BackOffice Resource Kit CD-ROM to create a home page for your users. You will need to create your own links.


Using SQL Workbook Publisher

For more information about using SQL Workbook Publisher, see SQL Workbook Publisher Help, installed with Publisher or Viewer on the Excel Help menu, or with the Browser components.


Removing SQL Workbook Publisher

There are three ways to remove SQL Workbook Publisher from your computer.

To Remove SQL Workbook Publisher from a SQL Server

This task is for database administrators.

Before removing SQL Workbook Publisher from your SQL Server, you must copy Remove.sql from the BackOffice Resource Kit CD-ROM to the computer running Windows NT Server.

Start Microsoft ISQL/w.

In the Server box, select the server from which you want to remove SQL Workbook Publisher.

In the Login ID box, type a valid login identification for the SQL Server. Be sure the login identification allows the database owner access to the database.

In the Password box, type the password for the login ID, and click Connect.

In the DB box of the Query window, select the database from which you want to remove SQL Workbook Publisher.

Click Load SQL Script, locate Remove.sql, and select it.

After the Remove.sql script appears in the query window, click the Execute Query button.

Repeat steps 5 through 7 for each database on the server from which you want to remove SQL Workbook Publisher.

You can quit Microsoft ISQL/w after all SQL Workbook Publisher objects have been removed.

To Remove SQL Workbook Publisher from an Excel Client

This task is for Excel users.

On the Windows Start menu, point to Settings, and click Control Panel.

Click Add/Remove Programs.

Double-click SQL Workbook Publisher or SQL Workbook Viewer.

To Remove SQL Workbook Publisher from the Intranet

This task is for Webmasters.

Find the IIS directory. The directory default name is Inetsrv on Windows NT Server 3.51 and InetPub on Windows NT Server 4.0.

Delete all SQL Workbook Publisher files from the Scripts\Sqlwpub directory, then delete the Sqlwpub directory.

Delete all SQL Workbook Publisher files from the Wwwroot\Sqlwpub directory, then delete the Sqlwpub directory.

Note If you want to remove references to only certain databases from the intranet, be careful to delete only the files referencing those databases from Scripts\Sqlwpub and Wwwroot\Sqlwpub.


SQL-DMO Code Samples

This Microsoft Visual Basic code can be used to add to your understanding of the SQL-DMO discussion in Part 6, "Programming for Microsoft SQL Server." The Dmosamp project and form can be added as needed to your own code.


Installing SQL-DMO Code Samples

If you ran the BackOffice Resource Kit CD-ROM Setup, you can access the SQL-DMO code samples from the Bork\Sql\Examples directory on your computer. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

To install SQL-DMO code samples

Get Dmosamp.vbp and Dmosamp.frm from the Sql\Examples directory on the BackOffice Resource Kit CD-ROM.

Start Visual Basic.

The sample was written using Visual Basic version 4.0.

Load the Dmosamp.vdp file.

This will automatically pick up the other program files, provided they are in the same directory.

Select the Dmosamp.frm from the Project window to view the code, and then click on the form controls to bring up the Code window.

On the Run menu, click Start. Alternatively, press the F8 key to step through the code.


Sqlhdtst Utility

Because of the rigorous system demands made by a production database server, Microsoft SQL Server will sometimes encounter problems in the underlying operating system or hardware which might appear as instabilities or errors. These problems could occur even though hardware diagnostics have run without reporting them, and other server applications on the system have generated no errors.

Sqlhdtst helps isolate these cases by performing a high-intensity, multithreaded file system stress test. It also exercises the Win32 overlapped, or asynchronous, I/O APIs. Sqlhdtst indicates a problem with an on-screen error. Because Sqlhdtst does not use any SQL Server components, any problem detected indicates a problem in the platform and not in SQL Server. These problems can exist at the hardware, controller, firmware, device driver, or operating-system layers.


Installing Sqlhdtst

Sqlhdtst is a single executable that can simply be copied to the Winnt\System32 directory on the Windows NT server to be tested. If you ran the BackOffice Resource Kit CD-ROM Setup, you can access the Intel x86 version of Sqlhdtst from the Start menu. Otherwise, install it from the BackOffice Resource Kit CD-ROM.

Note A full Sqlhdtst run should consume most of the processing resources on the server, reducing its ability to respond to other applications. For this reason, do not run Sqlhdtst on a server actively being used as a production server. The server's files should also be backed up prior to running Sqlhdtst.

To install Sqlhdtst

  • The Sql\Sqlhdtst directory on the BackOffice Resource Kit CD-ROM contains the Sqlhdtst version for DEC Alpha servers and the Sqlhdtst version for PowerPC servers, as well as the default Sqlhdtst for Intel servers. Copy the appropriate executable to the server's Winnt\System32 directory.


Implementing Sqlhdtst

Sqlhdtst can be run either by clicking on its icon or from the command prompt. This version of Sqlhdtst accepts command-prompt arguments, making it easier to run the utility from command files that fire off several simultaneous instances of Sqlhdtst.

Usage

When you run Sqlhdtst from the command prompt, it accepts the following options:

sqlhdtst [/D testfile] [/S size] [/I iterations] [/W nmbrwrites] [/T threads] [/M maxasync] [/Q threadasync] [/O outfile] [/B boost] [/R readaheadthreads] [/E readaheadextents]

where:

/D testfile

Is the full path to the file that Sqlhdtst will create for testing.

/S size

Is the size of the test file, specified in 2K pages.

/I iterations

Is the number of test iterations to run.

/W nmbrwrites

Is the number of writes to make in each iteration.

/T threads

Is the number of threads to use.

/M maxasync

Is the maximum number of asynchronous I/Os to have outstanding at any time.

/Q threadasync

Is the maximum number of asynchronous I/Os any individual thread can have outstanding at any time.

/O outfile

Is the name of a file to hold an output report.

/B boost

Indicates whether or not Sqlhdtst should run with boost priority on (1) or off (0). The default is off (0).

/R readaheadthreads

Is the number of readahead threads Sqlhdtst should use.

/E readaheadextents

Is the number of readahead extents each readahead thread should use.

When you run Sqlhdtst from an icon, you use a dialog box to fill in the above parameters. The dialog box appears when you click DiskTest/Run Test.

Remarks

If an error is detected, contact your system support provider.

If Sqlhdtst runs without reporting any errors, this does not mean the system is free of problems. It simply means Sqlhdtst did not encounter a problem. Problems could still exist that were not triggered by Sqlhdtst.

For meaningful results, run Sqlhdtst as follows:

  • Run at least four simultaneous instances of the program. Each instance will need to specify a unique file name.
  • Use a large file size. What constitutes a large file varies depending on your server and available free disk space. Try to use test files more than 50 MB in size, use much larger files when the space is available.
  • If you have multiple drives and/or disk controllers, ensure that at least one instance of Sqlhdtst places its file on each one.
  • While the disk tests are running, also run at least one instance, and preferably more, against network-based drives. For example, use as the test file path:

\\servername\c$\ftest.fil

where servername is the name of a network file server to which the Windows NT box being tested has access.

  • At a minimum, run the test overnight. Running the test for a few days, such as over a weekend, is best. Adjust parameters to ensure the test will run for the entire test period.
  • Because of the high resource load Sqlhdtst places on the system, you should not have the system in production nor be running SQL Server.
  • Because of the high CPU load Sqlhdtst places on the system, you may want to start Sqlhdtst from the command prompt, running in the IDLE priority class. This will not reduce the effectiveness of the test; however, it will help prevent the test from dominating the system to the point where a command session is unresponsive. For example:

start /low sqlhdtst

The test is also usually run without boost priority enabled.

  • When running Sqlhdtst from an icon, the dialog box presents small, medium, and large options to quickly configure tests. Using medium is a good choice for small server machines; this uses a 100 MB test file.
  • To effectively test a large server, use conditions such as:
    • Run at least four simultaneous instances of Sqlhdtst for the disk subsystem.
    • Concurrently run at least two instances of Sqlhdtst against network-based drives on a remote file server, if possible.
    • Start each instance using the START /LOW command.
    • Select a nonconflicting file name for each test file.
    • Place a separate test file on each disk or disk controller.
    • Select a file size greater than 100 MB. Make file sizes as large as possible.
    • For Number of Iterations of the test, select 2000.
    • For Number of Random Writes/iteration, select 10000.
    • For Number of Worker Threads, select 50.
    • For Max Async IO, select 255.
    • For Max Async IO per Thread, select 4.

Samples

To run a single test on a small server:

start /LOW sqlhdtst /Dc:\sqlhdtst\testfile.dat /S512 /I20 /W20 /T5 /M20 /Q4 /R3 /E3

To run a single test on a medium server:

start /LOW sqlhdtst /Dc:\sqlhdtst\testfile.dat /S51200 /I100 /W500 /T25 /M20 /Q4 /R6 /E6

To run a single test on a large server:

start /LOW sqlhdtst /Dc:\sqlhdtst\testfile.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12

To seriously stress test a large server that has c:, d:, e:, and f: physical disk drives:

start /LOW sqlhdtst /Dc:\testfil1.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12
start /LOW sqlhdtst /Dd:\testfil2.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12
start /LOW sqlhdtst /De:\testfil3.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12
start /LOW sqlhdtst /Df:\testfil4.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12
start /LOW sqlhdtst /D\\FileSrvr1\sharenm\testfil5.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12
start /LOW sqlhdtst /D\\FileSrvr2\sharenm\testfil5.dat /S512000 /I2000 /W10000 /T100 /M20 /Q4 /R12 /E12


Introduction

Welcome to the Microsoft SNA Server Resource Guide. This guide is designed for people who are, or want to become, expert users of Microsoft SNA Server. This guide is a technical supplement to the documentation included as part of the SNA Server product and does not replace that information as the source for learning how to use SNA Server.

This guide is included in the Microsoft BackOffice Resource Kit. The Microsoft BackOffice Resource Kit for SNA Server includes many tools you can use to support your SNA Server installation. For more information about SNA Server tools, see the SNATOOLS.HLP file on the Microsoft BackOffice Resource Kit CD-ROM.


About the Resource Guide

This guide includes the following chapters:

Chapter 1, "SNA Server Architecture," describes the client-server and management architecture of SNA Server. It includes how SNA Server computers communicate with other servers and clients on the network.

Chapter 2, "SNA Open Gateway Architecture," describes the architecture of SNA Server in central and branch network configurations.

Chapter 3, "SNA Server Support," describes how SNA Server works within SNA networks.

Chapter 4, "Network Management," describes the support that SNA Server provides for centralized network management.

Chapter 5, "Host Security Integration Architecture," describes how Host Security Integration works with SNA Server, Windows NT, and host computers.

Chapter 6, "Printer Definition Files," describes the format of files you can use to specify the capabilities of printers made available through SNA Server Host Print Service.

Chapter 7, "Sample Host Definitions," presents samples for SNA Server connections to IBM host systems.

Chapter 8, "Registry and Environment Variables for SNA Server," describes the Registry variables and environment variables that can be set for SNA Server.

Chapter 9, "Event Viewer Messages," lists the error and audit messages for SNA Server.

Chapter 10, "Performance Monitor Counters," describes the Performance Monitor Counters used to monitor SNA Server activity.

This guide also includes an index.


Conventions in the Resource Guide

The following table summarizes the typographic conventions used in this book.

Convention

Description

bold

Command-line commands, options, tool menus, and portions of syntax that must be typed exactly as shown.

Italic

Information you provide, terms that are being introduced, and book titles.

KEY+KEY

Key combinations in which you press and hold down one key and then press another.

Monospace

Examples, sample command lines, program code, and program output.

Small Capitals

Names of keys on the keyboard.


Where to Look for More Information

You can find additional information about SNA Server in the product documentation and on the SNA Server World Wide Web sites, as described in the following sections.


SNA Server version 3.0 Product Documentation

The SNA Server version 3.0 product documentation is located on the SNA Server CD-ROM. Hard copy versions (except for Getting Started) can be ordered from Microsoft using the card provided in the SNA Server product box. The online documentation includes both the basic documentation and SDK documentation.

Basic Documentation

Getting Started

This book presents the basic information needed for new users of SNA Server and provides the installation instructions. This book is included as a printed book in the SNA Server product box.

Administration Guide

This book explains conceptual information on how to administer Microsoft SNA Server. It includes information on the basic concepts of SNA architecture and SNA Server concepts. It explains SNA Server Manager, the new graphical interface for managing SNA Server. It also covers 3270 and APPC connectivity and sessions. Also included are descriptions of other SNA Server features such as AFTP, TN3270 service, TN5250 service, Shared Folders Gateway Service, Host Print Service, SNA Remote Access Service, Host Security Integration, Data Encryption, and ODBC/DRDA service.

Planning Guide

This book provides an overview of planning an SNA Server network and connectivity to host computers.

Reference

This book contains additional information about SNA Server. A glossary of frequently used terms is also included.

SDK Documentation

Microsoft SNA Server 3270 Emulator Interface Specification

This guide is intended for independent software vendors who are developing their own 3270 emulation client software to work with Microsoft® SNA Server. It provides the following information:

  • Internal concepts of SNA Server that are required to integrate 3270 client software.
  • Definitions of the interfaces used by the client software to communicate with SNA Server components.
  • Information on using SNA Server's configuration and diagnostics features.
  • Instructions for compiling and linking the client software with the necessary SNA Server-supplied files.

Microsoft SNA Server AFTP API Programmer's Guide

The Advanced Program-to-Program Communications (APPC) Application Suite provides application programming interfaces (APIs) to its APPC File Transfer Protocol (AFTP) functions. It provides the information you will need to write an application program to implement AFTP client functions.

Microsoft SNA Server APPC Programmer's Guide

The Microsoft SNA Server APPC Programmer's Guide provides the information required to develop C-language applications that use Advanced Program-to-Program Communications (APPC) to exchange data in a Systems Network Architecture (SNA) environment.

Microsoft SNA Server Client Setup

This book provides information regarding the installation of the SNA Server Client binaries. This information will enable you to consolidate SNA Server into your product's own setup, simplifying operation for the end user.

Installation information is provided for the following environments:

  • Windows 3.x (16-bit Windows)
  • Windows NT and Windows 95 (Win32®)

This information should allow you to integrate the installation of the SNA Server client binaries with your own product.

Microsoft SNA Server CPI-C Programmer's Guide

This book provides information required to develop C-language applications that use the Common Programming Interface for Communications (CPI-C) to exchange data in a Systems Network Architecture (SNA) environment.

This guide is intended for the programmer writing applications that use CPI-C to exchange data. It provides conceptual information and detailed reference information.

Microsoft SNA Server LUA Programmer's Guide

This book explains how to develop C-language applications that use the conventional Logical Unit Application programming interface (LUA) to exchange data in a Systems Network Architecture (SNA) environment.

This implementation of LUA is compatible with the Request Unit Interface (RUI) and the Session Level Interface (SLI) of LUA for the Microsoft Windows NT® operating system, the Microsoft Windows® 95 operating system, the Microsoft Windows® graphical environment, and the IBM Extended Services for OS/2 version 1.0.

Microsoft SNA Server SNA Print Server Data Filter

This section introduces the SNA Print Server Data Filter API (sometimes referred to as the Print Exit API) that can be used to extend the capabilities of SNA Print Server.

Microsoft SNA Server SNA Device Interface Specification

This guide is intended for OEMs and adapter vendors who are developing their own SNALink software to work with Microsoft® SNA Server. It provides the following information:

  • Internal concepts of SNA Server that are required to integrate new communications adapters into the server environment.
  • Definitions of the interfaces used by SNA Server to communicate with SNALinks.
  • Information on using SNA Server's configuration and diagnostics features.
  • Instructions for compiling and linking the SNALink support software.

Microsoft SNA Server National Language Support

This book describes the features available in SNA Server for supporting international languages and different national language character sets. Introduced with SNA Server version 3.0, the SNANLS API available on Windows NT and Windows 95 can be used to support international languages in SNA applications by means of a standardized and consistent interface.


SNA Server Web Sites

You can visit the following Web sites for current information about SNA Server:

http://www.microsoft.com/sna The SNA Server Web site contains current information about SNA Server including helpful information about planning, migration, and deployment.

http://www.microsoft.com/TechNet/ The Microsoft TechNet Web site contains information about subscribing to the Microsoft TechNet, which provides in-depth technical information about Microsoft's business products, including SNA Server and other Microsoft BackOffice products.

http://www.microsoft.com/train_cert/ The Microsoft Training and Certification Web site provides information about training options and the Microsoft Certified Professional Program.


Contributors

This book is dedicated to all the hard working writers, editors, reviewers, and numerous production staff people at Microsoft who make books like this possible. Thank you!

Contributors to this book include the following:

Lead Technical Writer:
Karen Kennedy

Program Manager
Ben Gamble

Technical Editor
Mary Harris

Technical Consultants
David Ashby, John Docherty, David Downing, Steve Dudgeon, Charles Ezzell, Stuart Flower, Andy Gillcrist, Darin Green, Bob Hyman, Antero Koskinen, Paul Larsen, Paul Morse, Saurab Nog, Steve O'Sullivan, Henry Rawas, Kraig Rury, Steve White

Production
Dan Bejesky

Graphic Designers
Autumn Sheppard, Jan Yeager, Gabriel Varela, Martin Fernandez

Indexer
Julie Hatley


Chapter 1 SNA Server Architecture

SNA Server installations are increasing. Some customer sites have over 10,000 users using thousands of LUs in a single subdomain. The newly redesigned SNA Server Manager allows the administrator to immediately obtain the status of each SNA Server computer in every subdomain while reducing the load on the LAN and on the server computers and while improving response times.

SNA Server Manager incorporates many new features and a new proxy-agent architecture for management information. SNA Server Manager was redesigned to be extensible and scaleable.

SNA Server Manager provides the ability to monitor multiple subdomains. This encourages limiting subdomains to a small size (a maximum of 15 SNA Server computers) for easier management and administration.

New services are integrated into SNA Server, along with new management objects. The new services include Shared Folders, AFTP, Host Print Service, TN3270, TN5250, SNA Remote Access Service, and Host Security.

The ability to access management data from applications other than SNA Server Manager will become increasingly important as OLE becomes more prevalent and administrators create their own scripted applications. This requires not only an automated OLE interface, but also the ability to support several concurrent applications accessing the same data. SNA Server is designed for these future enhancements.

This chapter explains SNA Server and some of its underlying architecture.


SNA Server Architecture Overview

The architecture of SNA Server and its clients was designed to support two kinds of communication: those between client and server, and between server and management workstations. The components allow client computers to communicate with SNA Server computers and vice versa over local-area and wide-area networks. The architecture of SNA Server is best described in two pieces—the client-server architecture and the management architecture—with an explanation of how each manages data.

The client-server architecture allows applications to communicate data between server and client computers. It uses the SnaBase, SnaServer, and SnaDMOD services and network protocols such as TCP/IP, and IPX/SPX to achieve communication. Figure 1.1 provides an overview of the server architecture.

Figure 1.1 An overview of SNA Server architecture.

These services work with SnaBase and WINRUI, WINSLI, WINAPPC, and WINCPIC DLLs to provide the fundamental service of SNA Server: support for applications written to SNA APIs. These APIs run on application clients without the complexity and redundant overhead of a full SNA protocol stack on each client. Figure 1.2 provides an overview of the client architecture.

Figure 1.2 An overview of SNA Server client architecture.

The management architecture in SNA Server uses Manage Agent (MngAgent) and Manage Client (MngCli) to manage services, maintain connections, and transfer information. It can be directed to make decisions on filtering information transmitted over the LAN to management clients to avoid large bursts of traffic that swamp the transports. When a change occurs on an SNA Server computer, MngAgent decides whether to send it to the client via MngCli. Changes in LU status, adding new users and starting or stopping of an APPC session are some of the changes that MngAgent monitors and directs. Queues on both server and client computers act as temporary holding areas for data transfer. Figure 1.3 provides an overview of how the management architecture allows communication between server and client.

Figure 1.3 An overview of how SNA Server computers and client computers communicate with each other.

The client-server architecture and management architecture use the DMOD transportation protocol. How DMOD interacts with each component is discussed in the following sections. The important characteristics of DMOD are:

  • It is protocol-independent and supports TCP/IP, IPX/SPX, Microsoft Networking/NetBIOS, Banyan VINES, and AppleTalk.
  • It supports multiple links simultaneously.
  • Is able to send and receive variably sized messages.

It provides a nonblocking operation.

DMOD is a specialized form of the Remote Procedure Call (RPC) facility and is proprietary to SNA Server. For more information about DMOD, see the topic "How Do I Secure SNA Server?" in the Microsoft SNA Server Administration Guide.


SNA Server Client-Server Architecture

SNA Server running on server machines in the network uses SnaBase, SnaServer, and SnaDMOD to communicate with API DLLs residing on client computers. Information is transferred via the DMOD transportation layer.

SNA Server's many processes perform different functions and operate in an interrelated manner. The services in SNA Server can exchange messages between themselves and across the network. SNA Server uses SnaBase, SnaServr, and SnaDmod to perform various important functions on the server computer. Figure 1.4 shows detailed diagram of the server architecture.

Figure 1.4 This figure depicts the components SNA Server architecture uses to communicate with other server computers and clients on the network.

Four major APIs are used to support SNA sessions: Request Unit Interface (RUI), Session Level Interface (SLI), Advanced Program-to-Program Communication (APPC), and Common Programming Interface Communication (CPI-C). RUI and SLI, also collectively called Logical Unit Application (LUA), use LU profiles 0 through 3 over dependent LUs. APPC and CPI-C use LU profile LU6.2 over either dependent or independent LUs. For more information regarding LUA and APPC, see the Microsoft SNA Server Administration Guide and the IBM publication, SNA Technical Overview, document GC30-307.

SNA Server provides DLLs to support each of these APIs for SNA applications running on clients: WINRUI, WINSLI, WINAPPC, and WINCPIC. All four API

DLLs translate the SNA API into client-server messages that are then sent through DMOD to an SNA Server node or nodes on the network. SNA Server also supports proprietary APIs for legacy 3270 emulation products: the "3270 Emulator Interface" or the "Function Management Interface (FMI). The FMI API DLL does not exist; applications using FMI interface directly with DMOD.

All four APIs provide the same basic application services: access to SNA LU sessions. The multiple APIs provide compatibility with the SNA architecture as it has evolved over more than 20 years of use. APPC and CPIC are new APIs, and many applications require the use of the older LUA. Figure 1.5 shows a detailed diagram of the client architecture.

Figure 1.5 This figure depicts how the various components of the SNA Server client architecture work to communicate with SNA Server.

WINRUI and WINAPPC are event-driven DLLs. When a request is issued, the client can continue to perform other tasks while waiting for notification to come back that the request has completed (asynchronous communication).

WINSLI and WINCPIC are API DLLs that support session-oriented APIs. When a request is issued, the verb needs to be synchronized with the program. Until the request is completed, the client cannot go on to other tasks (synchronous communication).

SNA Server clients communicate with SNA Server computers using network protocols such as TCP/IP, IPX/SPX, Microsoft Networking, and Banyan VINES.

For a detailed discussion of the network protocols, see Appendix A in the Microsoft SNA Server Planning Guide and the section "How Does SNA Server Communicate with Client Computers" in the Microsoft SNA Server Administration Guide.

Other services provided by SNA Server are also implemented as client SNA applications based on one of the four API DLLs. These include TN3270, TN5250, Shared Folders Gateway, Host Print Service, Host Security Integration, and SNA Remote Access Service. These services are discussed in detail in the Microsoft SNA Server Administration Guide and in the SNA Server Manager online Help.


SnaBase

SnaBase runs on both client and server computers, but performs slightly different functions on each. SnaBase dynamically maintains a service table of SNA Server computers, links, and invokable TPs in the subdomain. It supports client-sponsor connections that are used to send the server list to the client. It is also is responsible for initializing SnaDMOD and uses SnaDMOD to send messages to other components in the network via sponsor connections.

A sponsor connection is an initial connection between a client and an SNA Server computer. This connection provides the client with all the names of the SNA Server computers in the subdomain. The client uses these names to locate resources, such as LUs, in the network. For example, if a resource is an LU, the server SnaBase provides the client with the name of the server on which the LU resides. If the resource is an LU pool, the server provides the client with a list of servers associated with the pooled LUs. The client tries each server in random order until it finds a server with a free LU.

SnaBase on a server computer also initializes shared memory updates. The information that SnaBase sends depends on whether it is directed to the client or another SNA Server computer in the subdomain.

When the information is sent to the client, SnaBase determines the size and the list of servers available to the client depending on the operating system of the client computer (Windows NT, Windows 95, Windows 3.x, DOS, Macintosh, OS/2, or UNIX). Usually, the information is limited to a list of SNA Server computers in the subdomain.

On a Windows NT Server computer, SnaBase provides the complete service table, including the names of SNA Server computers (also referred to as nodes) in the subdomain, all available services, invokable transaction programs (TPs), and APPC information. All of these are updated frequently using server-to-server broadcasts or directed datagrams depending on the server-to-server communication protocol.


SnaServer

The SNA protocol engine of SNA Server implements the SNA protocol profiles of PU 2.0 and PU 2.1. SnaServer is the component of SNA Server that interacts with client computers and other nodes on the SNA network, using the four DLLs. SnaServer also provides up-to-date status to SNA Server Manager, providing real-time display information on servers, clients, connections, LUs, and users.


WINRUI

WINRUI implements the Request Unit Interface (RUI) API to access dependent LUs. It can drive either LUA LUs or 3270 LUs configured in SNA Server Manager.


WINSLI

WINSLI implements the Session Level Interface (SLI) API to access dependent LUs. It can drive either LUA LUs or 3270 LUs configured in SNA Server Manager.

The most common application for RUI and SLI is 3270 terminal emulation for access to SNA mainframes. The next most common application is a broad class of LU0 applications that support a variety of custom applications in the financial services industry.


WINAPPC

APPC is an API that allows peer-to-peer communications in an SNA environment using LU 6.2 over either dependent or independent LUs. Through APPC, programs distributed across a network can work together, communicating with each other and exchanging data, to accomplish a single processing task such as querying a remote database, copying a remote file, or sending and receiving electronic mail.

A detailed description of APPC APIs is found in the Microsoft SNA Server APPC Programmer's Guide.


WINCPIC

WINCPIC provides support to the CPI-C API using LU 6.2 over either dependent or independent LU6.2 LUs.

A detailed description of CPI-C APIs is found in the Microsoft SNA Server CPI-C Programmer's Guide.

APPC and CPIC are widely used by end-user organizations to communicate with their SNA mainframes and midrange systems.


SNA Server Management Architecture

SNA Server uses MngAgent and MngCli to manage services and resources, and to report the status of the services and resources to the Manager. The management architecture works to direct the flow of management data between server computers and administration clients.

In SNA Server, the services write data into the management object, which in turn notifies Manage Agent (MngAgent). If clients currently connected to the server need notification of the change, MngAgent sends the information to Manage Client (MngCli) on the client computer via DMOD. This information is then downloaded to the shared management object, which in turn notifies the Manager on the client computer.

Other applications besides SNA Server Manager may run on a client computer to request status or control the same set of services and resources. More than one such application may run at the same time. MngCli will maintain a single copy of the management data, and a single set of links to MngAgent, to support all the applications. Typically MngCli will open a link to all the servers in the SNA Server subdomain that it is managing. For each server, MngCli will have a single link to the MngAgent on that server. The management data from all the servers will be merged to represent the all the services and resources for the subdomain.

MngAgent will maintain a single copy of the management data for the server on which it is running. The management data from all the services and resources on that machine will be merged to represent the server. MngAgent can accept links from more than one MngCli at the same time, allowing multiple administration clients to monitor and manage the server.


SNA Server Management Architecture Components

The following picture diagrams the layers of SNA Server:

Figure 1.6 This figure depicts the various components of
SNA Server management architecture.

Manage Agent Layer (MngAgent)

Manage Agent runs as a service on the server computer and exchanges data with the corresponding management proxy on the client (Manage Client). Changes in the state of some management data are selectively sent to the Manage Client. Commands and requests from a Manage Client are accepted by Manage Agent and reflected down to the Manage objects. Having a central module allows for the addition of extra features that may eventually include flow control, compression, and more. MngAgent must be running on SNA Server computers, or the service will show an Offline status in SNA Server Manager.

Shared Management Object Layer

The shared management object layer is a temporary holding area, storing data about SNA Server services and resources. When a change occurs in a service, the information is written into shared management.

Shared Management Objects

Access to shared memory is via a set of objects. Objects contain data about the various components of SNA Server. Each process has its own copy of the object interfacing to shared memory. The object provides a wrapper for changes to shared memory, and will propagate change notifications to all the processes that

have requested notification for that object. Each process may have only a subset of the complete object set. The actual object data is common for all the processes. The objects also enforce access control on the data to prevent conflicts (mutual exclusion).

Each shared management object keeps track of which processes have a reference to the shared data, and what type of notifications each process has requested per object.

Agent Notify Queue

The Agent Notify Queue is used to queue update notifications from the underlying management objects, and to dispatch the queued notifications to the proper place for handling. Each process creates a "notify queue" for receiving events. The events are dispatched to the "notifysink" that is registered to accept messages for the manage object that generated the event. If a new manage object is created, notification is sent to the sink of the parent object.

The Agent Notify Queue resides in shared memory, allowing the service process to place notifications in the queue, and the MngAgent to remove and process the notifications.

Service Notify Queue

The Service Notify Queue is used to queue requests, commands, and notification of changes to the underlying management objects, and to dispatch the queued notifications to the service process for handling. It is identical to the Agent Notify Queue, except that the source and destination are switched.

The Service Notify Queue resides in shared memory, allowing the Agent process to place notifications in the queue, and the service process to remove and process the notification.

Notify Sinks

Each process that requires notification of events to manage objects will create a Notify Sink. The Notify Sink is the destination object of an event notification. The sinks do not exist in the shared management objects layer; however, they are used when needed. The Notify Sink receives notification after information is taken out of the queue by a process.

Service Format Layer

This layer is used to isolate a service from the management object layer. Each service may provide an agent DLL that gathers the data from the service and passes it to the shared objects. Similarly, commands and requests coming from the shared management objects are passed via this layer.

A special case of this is used to support the SNA Server service itself. Management data and commands are exchanged with the SNA Server service via shared memory links in the DMOD. These links existed in previous versions of the SNA Server product. To minimize risk, these interfaces were left unchanged in the 3.0 version. An extension to MngAgent was written to convert the old interface to the new shared management objects. This extension runs as part of the MngAgent service process, and is contained in SNAMANAG.DLL and MNGSNA.DLL.


SNA Server Client Management Architecture Components

The client architecture includes the following components:

  • OLE Controller Applications
  • OLE Server/API Application
  • Administration Items
  • Configuration (SNACFG)
  • Shared Management Objects Layer
    • Shared Management Objects
    • App Notify Queue
    • Proxy Notify Queue
    • Notify Sinks
  • Client Server Comms Layer
    • Manage Client (MngCli)
  • Transport Layer

The following picture diagrams the layers of the client management architecture.

Figure 1.7 Client management architecture components.

OLE Controller Applications

The top layer of the architecture presents SNA Server Manager information to the user. This includes the SNA Server Manager user interface and automation controllers (such as a Visual Basic application). They typically deal with configuration and management data, and receive notification of changes to the data either by polling or by implementing a special OLE object that is used to inform the application of changes to the underlying objects. The applications open a domain to initiate the reading of the configuration file and obtaining of status data from all SNA Server computers in a subdomain.

OLE Server / API Application

The second layer consists of OLE servers for configuration and management data. The OLE servers allow access to the properties and status of a service or resource, an interface for sending commands, and some control functions to facilitate the display of the objects. Communication is achieved with C++ objects in one or more DLLs. The OLE servers are little more than wrappers of the third layer into OLE objects.

Items

The third layer is made up of C++ objects. It links the configuration data and the status information of an object. Every configuration record and management data object must be linked to an item. An item may or may not have a corresponding OLE server object, but every OLE server object must have an item. This is the central glue that holds together the data and the presentation of the data.

Configuration (SNACFG)

This layer is the interface for accessing configuration information. The SNACFG.DLL provides an interface for reading and writing the configuration file and for accessing the various records in the file. It is also used by other parts of the system that need to be configured. SNACFG will support extensions by allowing new record types to be dynamically defined and stored in the configuration file. This preferred method of storage provides a common interface, as well as coherent security, replication, and backup mechanisms.

Shared Management Objects Layer

Multiple management applications can be active simultaneously and share the same management objects. A separate process is responsible for maintaining all the client-server links for a client workstation, which prevents the creation of client-server links for each active application. The combined set of management data is kept in shared memory, where all the client application processes can access it. This is a management database for all the objects that the client machine is managing.

Shared Management Objects

Access to shared memory is via a set of objects. Objects contain data about the various components of SNA Server. Each process has its own copy of the object interfacing to shared memory. The object provides a wrapper for changes to shared memory, and will propagate change notifications to all the processes that have requested notification for that object. Each process may have only a subset of the complete object set. The actual object data is common for all the processes. The objects also enforce access control on the data to prevent conflicts (mutual exclusion).

Each shared management object keeps track of which processes have a reference to the shared data, and what type of notifications each process has requested per object.

App Notify Queue

The App Notify Queue is used to queue update notifications from the underlying management objects, and to dispatch the queued notifications to the proper item for handling. Each process creates a "notify queue" for receiving events. The events are dispatched to the "notifysink" that is registered to accept messages for the manage object that generated the event. If a new manage object is created, notification is sent to the sink of the parent object.

The App Notify Queue resides in shared memory, allowing the MngCli process to place notifications in the queue and the client application process to remove and process the notifications.

Proxy Notify Queue

The Proxy Notify Queue is used to queue requests, commands, and notification of changes to the underlying management objects, and to dispatch the queued notifications to the proxy process for handling. It is identical to the App Notify Queue, except that the source and destination are switched.

The Proxy Notify Queue resides in shared memory, allowing the App process to place notifications in the queue and the proxy process to remove and process the notification.

Notify Sinks

Each process that requires notification of events to manage objects will create a Notify Sink. The Notify Sink is the destination object of an event notification. The sinks do not exist in the shared management objects layer; however, they are used when needed. The Notify Sink receives notification after information is taken out of the queue by a process.

Client Server Comms Layer

This layer uses Manage Client and Domain control to provide data exchange between clients and SNA Server computers in the subdomain.

Manage Client (MngCli)

This module links the actual manage data on the servers with the shared manage objects. MngCli is started by the SNA Server Manager on the client computer. MngCli opens a connection with each MngAgent in the subdomain through which all management information flows. MngCli receives and sends messages from the SNA Server computers via Manage Agent (MngAgent). It uses the received messages to create, modify, or destroy shared management objects. It accepts commands and notifications from management objects (via a Notify Sink) and sends messages to SNA Server computers.

Domain Control

Domain control is responsible for opening and closing subdomains, discovering the location of configuration servers, and security. It keeps a reference count per subdomain to track when an open subdomain should actually be closed.


Chapter 2 SNA Open Gateway Architecture

Organizations with IBM® mainframe or AS/400® computers are consolidating their SNA-only and non-SNA networks into single TCP/IP-based wide area networks (WANs). In the past, two parallel networking systems have been deployed in most organizations: the traditional SNA network, used to connect PCs and hardware controllers with IBM mainframes and AS/400s; and local area networks (LANs), used primarily to access files and client/server applications running on local server computers.

During the past few years, there has been a dramatic increase in the number of organizations seeking a single WAN solution that provides access to all desktops, servers, and host systems across a single networking protocol. At the same time, TCP/IP is emerging as the protocol of choice because of its versatility, openness, and ability to support Internet and intranet connections.

Preventing many organizations from integrating their networks is the need to ensure reliable and secure access to existing IBM host systems — on which most organizations base their mission-critical daily operations.

SNA Open Gateway Architecture (SOGA), satisfies the requirement for reliable and secure host connectivity in the context of an integrated WAN. SOGA is a scalable framework for SNA enterprise connectivity offering multiple options for integrating branch offices via routed internetworks with IBM mainframe and AS/400 computers. This framework encompasses components from leading channel attachment and internetworking vendors, while deploying SNA Server computers in both traditional and innovative ways.

SOGA supports industry standards for SNA host access and presents flexible options for integrating host data across open WANs, such as those composed of Data Link Switching (DLSw), Frame Relay (RFC 1490), and Asynchronous Transfer Mode (ATM). Request for Comment (RFC) 1490 specifies methods of encapsulating TCP/IP and SNA within Frame Relay. The SOGA blueprint consists of three core elements:

  • Flexible SNA gateway deployment models;
  • High-performance SNA gateway configurations
  • Efficient wide-area network utilization.


The Trend in PC-to-Host Connectivity

Traditionally, PC desktops have been directly connected to IBM host systems, using SNA-only hardware adapters and SNA protocols across a dedicated SNA-only network. Initially, this meant installing a coax or twinax adapter in each PC, which was connected via coaxial or twinaxial cabling to a local IBM control unit, such as an IBM 3174 or IBM 5294. Later, this meant using a token-ring LAN adapter to connect PCs to controllers via the SNA Data Link Control (DLC) protocol. Control units in remote locations were connected to central host systems across leased-line Synchronous Data Link Control (SDLC) connections.

However, at the same time as organizations moved from coax and twinax to token-ring LANs, there emerged a greater need for access to non-SNA LAN file servers to meet the daily needs of PC users. For the most part, the SNA networks remained separate from the non-SNA networks. Each network had its own PC adapters, cabling, and protocols. The non-SNA LANs tended to be built across Ethernet using popular IPX/SPX or TCP/IP protocols. Non-SNA LANs were connected together over WANs composed of routers and bridges that supported non-SNA protocols only. Remote SNA controllers remained isolated on dedicated SNA-only SDLC leased lines.

Over time, organizations began merging SNA-only networks with non-SNA networks because maintaining separate SNA and TCP/IP networks was economically undesirable.

The first step towards integration was to use the same PC adapters and network cabling. Various industry standards and vendor-specific implementations have emerged to let SNA and non-SNA protocols share the same network. However, organizations learned through experience that mixing SNA and IPX/SPX or TCP/IP is like mixing oil and water. This is especially true in the case of WAN connections, where common reliability problems include DLC time-outs, poor and inconsistent host response times, and complex network management.

One remedy proposed by vendors has been to install a TCP/IP stack directly on the host system. However, this approach has its own disadvantages. Again, experience has shown that host performance often is degraded. In addition, some applications (such as host printing and host database access) will not work or require an investment in new TCP/IP-aware software. Also, IP address administration can present a far bigger network management challenge than supporting dual SNA and non-SNA networks. For more detail on these points, see "Integrating IBM Mainframes with TCP/IP Networks," a white paper produced by the SNA Server product unit, and "TCP/IP Connectivity in an AS/400 Environment," a white paper produced by Duke Communications and published

by NEWS/400 magazine. See "Integrating IBM Mainframes with TCP/IP Networks" on Microsoft's World Wide Web site at http://www.microsoft.com/sna. See also "TCP/IP Connectivity in an AS/400 Environment" on Duke Communications World Wide Web site at http://www.news400.com/Education/WhitePapers/tcpip/tcpip.htm.

Another remedy proposed by networking vendors is the concept of a LAN-to-SNA gateway. The gateway computer allows the PC desktops to access host applications and data using non-SNA protocols. The connection between the desktop and the gateway is via a common LAN protocol, while the connection between the SNA gateway and the host computer is via SNA. Microsoft SNA Server has the capability to provide LAN-to-SNA gateway services while providing a choice of network protocols, including TCP/IP, IPX/SPX, Banyan® VINES®, Microsoft Networking, and AppleTalk®.

LAN-to-SNA gateway solutions have become the de facto standard in providing access to host-based SNA applications for LAN-based PCs. One of the strongest motivations for using SNA gateways is to configure a single non-SNA protocol on every desktop, which improves stability of popular Windows® desktops and reduces PC memory usage. Other common features of SNA gateways include logical unit (LU) pooling, load balancing, and fault tolerance. These features provide greater availability of host logical units (LUs) and higher reliability of host connections.

Figure 2.1 SNA Server offers LAN-to-SNA gateway services supporting a broad range of LAN-based PC operating systems across popular LAN and WAN protocols.

Recent trends indicate that organizations are deploying large numbers of branch-based PCs that access multiple host systems through centralized SNA gateways. Centralized SNA gateway solutions offer high-speed channel and LAN-to-host connections. They also restrict the use ofSNA to the data center. However, this practice has revealed that most WANs cannot support heavy client-to-server (SNA gateway) traffic. The greater the number of clients, the slower the response time and the greater overhead on the wide-area network. This has prompted organizations to increase WAN backbone speeds, resulting in significant additional operating costs.

The typical network manager is now faced with the trade-off between (a) administrative savings offered by SNA gateway solutions and (b) the cost of additional network bandwidth required to achieve acceptable response times. In many cases, these trade-offs can be resolved by deploying SNA gateways to maximize available WAN resources. SOGA includes a number of flexible SNA gateway deployments that allow network managers to achieve the benefits of SNA gateway services without incurring prohibitive WAN operating costs.


Flexible SNA Gateway Deployment Strategies

SOGA offers three models for SNA gateway deployment in an enterprise network: branch-based, centralized, and distributed. The branch-based model is the traditional way to deploy SNA gateways, in which the SNA gateway is placed in branch offices and communicates with the host using SNA protocols, either via SDLC leased-lines or via DLC that is bridged or tunneled across the WAN.

In a centralized model, the SNA gateways are placed at the data center and connect to the host using SNA protocols, such as high-speed token-ring or channel attachment. The centralized model has emerged recently as a means to isolate the SNA traffic to the data center, thus avoiding the need to support SNA on the WAN. The centralized SNA gateways provide split-stack or TN3270 service for local and remote desktops that connect to the gateways using standard LAN protocols. Microsoft SNA Server has for some time supported both the branch-based and centralized deployment models.

The distributed model was originally proposed by Microsoft as a key element of SOGA and supported through a capability in SNA Server called the distributed link service. The distributed link service, which became available in Service Pack 1 for SNA Server 2.11 (Service Pack 1 for SNA Server 2.11 is available free of charge to existing SNA Server 2.11 customers. The Service Pack can be ordered on CD-ROM, by contacting Microsoft Sales, or can be downloaded from Microsoft's Internet FTP server), enables SNA Server to be deployed concurrently at branch and central sites. The branch-based SNA Server computers provide client-to-server support and connect to the central SNA Server computers using TCP/IP, IPX/SPX, or Banyan VINES protocols. The central

SNA Server computers provide server-to-host support and connect to the host via high-speed token-ring or direct channel attachment using SNA protocols.

The distributed deployment approach provides greater flexibility and better cost-effectiveness than either of the branch-based or centralized approaches alone. Compared to a branch-based deployment, the distributed approach eliminates the time-outs associated with bridging or tunneling 802.2 using routers, improves host response times, and simplifies network management. Compared to a centralized deployment, the distributed approach decreases WAN usage and supports NetView® management of the branch-based SNA Server computers.

The three SNA gateway deployment models are not mutually exclusive. In fact, depending on variables such as multiple host locations, an organization might implement one, two, or all three of these deployment strategies in combination. On the following pages, we will examine each approach in more detail.


Branch-Based SNA Gateway Deployment

Figure 2.2 SOGA encompasses the traditional way to deploy SNA gateways in branch offices, via SDLC leased-lines and X.25 connections to the host.

The branch-based model is the traditional way to deploy SNA gateways. In a branch-based configuration, the SNA Server computers are located remotely in the branch offices near the end users. Clients use LAN protocols to communicate with a local SNA Server computer. The SNA Server computers use SNA protocols to communicate with the host systems, which are generally centrally located. In a large enterprise, host systems could reside at multiple central locations. See Figure 2 for a depiction of a traditional branch-based deployment.

Traditionally, the connection between a branch-based SNA Server computer and a host system is across SDLC leased lines. SNA gateways are often used as replacements for remote control units, such as the IBM 3174 or IBM 5294. Clearly, the trend is towards bridging and tunneling DLC across a multiprotocol LAN using DLSw, RFC 1490, or ATM. However, not all organizations are ready to rely on a single interconnected WAN supporting both SNA and non-SNA traffic. Many organizations have invested in leased SDLC lines or X.25 connections between remote and central sites. These organizations find it advantageous to continue using these SNA-only data links. In the majority of cases, the reasons for staying with SDLC and X.25 involve not only cost but also an aversion to risk. SNA Server supports SDLC and X.25 connections, making use of existing SNA infrastructure where appropriate.

Advantages of a Branch-based Strategy

There are many advantages to following a branch-based SNA gateway deployment strategy. These include a better use of limited bandwidth on dedicated SNA-only data links and WAN; a step toward migrating to a TCP/IP or other single-protocol WAN; installation and use of multipurpose server computers in branch offices; and management of host access needs locally in the branch office.

Better use of limited bandwidth on dedicated
SNA-only data links and WAN

A branch-based SNA Server computer consolidates SNA session traffic, effectively providing physical unit (PU) concentration. When compared to directly connected DLC or SDLC workstations, a branch-based approach is more cost-effective. If an organization has implemented a TCP/IP or other open WAN, then isolating the SNA traffic to traditional SNA-only links reserves the WAN bandwidth for non-SNA purposes.

A step toward migrating to a TCP/IP or other single-protocol WAN

Figure 2.3 A branch-based deployment can use an existing
or future DLSw, Frame Relay or ATM WAN.

One of the advantages of deploying an SNA gateway is to make better use of current investments in SNA data links while allowing for a migration to either a single TCP/IP or other open-protocol WAN environment. As organizations migrate towards an SNA-free wide area network, they can tunnel the SNA protocols (DLC and SDLC) from the branch office LAN to the central site LAN by deploying routers or Frame Relay Access Devices (FRADs) supporting DLSw, frame relay (RFC 1490), or ATM.

Installing and Using Multipurpose Server Computers in Branch Offices

A single Windows NT® Server computer located in a branch office can use the Windows NT Server operating system's scalability to function as a multiapplication departmental server. The branch-based server can assume a number of roles, from SNA gateway platform to file and print server. Additionally, this computer can perform duties as e-mail server, database server, systems management server, and intranet server.

Managing Host Access Needs Locally in the Branch Office

A branch-based deployment has the added benefit of locating the SNA gateways near the clients requesting the host access services. This allows for local administration of SNA Server. Local SNA Server administrators can add or remove local users as needed, often resulting in more responsiveness to users' needs than relying on a central MIS group. However, this option requires SNA-speaking administrators on-site. Fortunately, local administration of SNA Server is optional. SNA Server supports full remote configuration and management across LAN, WAN, and Windows NT Server Remote Access Service (RAS) links. This lets organizations more flexibly administer branch-based SNA gateways using local or remote personnel.

Disadvantages of a Branch-based Strategy

The disadvantages of following a branch-based SNA gateway deployment strategy including difficulty in sharing host access resources across branch offices, and inability to provide high-speed host connections.

Difficulty in Sharing Host Access Resources Across Branch Offices

It is not easy to share resources across multiple SNA Server computers unless the servers are at the same location. For example, if Branch1 and Branch2 are connected by a WAN that allows the clients to connect to remote SNA Server computers (Client1 in Branch1 can connect to SNA Server in Branch2; Client2 in Branch2 can connect to SNA Server in Branch1), then it is possible that the client startup will be slow and the WAN bandwidth will be used poorly. ..The following are some suggestions for avoiding the above problem:

  • SNA Client Startup. The SNA Server client-server architecture includes an application-specific name service that operates over all supported client-server transports. The client maintains a "sponsor" connection to any one SNA Server computer in the subdomain. Over the sponsor connection, it gets the names and IP addresses (or other transport-dependent address) of all the other SNA Server computers in the subdomain. Then, when the client wants to open an SNA session, it goes through the list of server addresses in random order, looking first for an active connection with available session capacity, or, failing that, session capacity on a backup connection that could be activated on demand. Also, the "other servers" optional parameter can be used to cause the client to try one or more SNA Servers located outside of the subdomain. However, this is not advisable if the WAN bandwidth cannot support client-to-server connections between branch sites. Since the client tries the servers in random order, there may be a delay during initial client session startup if there are many servers in the subdomain but only a few servers supporting the LUs being requested, or if the servers are accessed across slow-bandwidth routed or bridged networks. To minimize initial client session startup time, the number of SNA Servers in a subdomain should be limited.
  • Server-to-Server Communications. It is not advisable to implement an SNA Server subdomain across branch sites using slow bridges or routers. This is because multiple SNA Server computers in a single subdomain can produce server-to-server communication activity that creates unwanted traffic on the wide-area network. By implementing a branch configuration with a local subdomain for each branch, this problem is avoided. These subdomains can still be part of a larger Windows NT domain spanning multiple remote sites to allow for centralized management of user and group accounts and permissions.
Providing High-Speed Host Connections is Not an Option

With a branch-based deployment, you cannot use channel attachment options or other high-speed links to the host. A direct channel attachment is the most efficient way to connect an SNA Server computer to a mainframe. There are two channel-attachment technologies: Bus & Tag, and ESCON® (Enterprise System Connection). Bus & Tag is a copper parallel-wire attachment that runs at 4.5 megabytes per second (MBytes/sec). The maximum distance is limited to a few hundred feet; therefore, a branch-based SNA Server computer cannot use Bus & Tag. ESCON is fiber cable-based, running at 17 MBytes/sec, and can be extended to around 10 miles using standard fiber repeaters. Even in the case of ESCON, a channel attachment solution is not easily provided to a branch site. High-speed token-ring or Ethernet connections are also rare in a branch-based configuration, because of limitations in most existing SNA-over-WAN technologies. See "Integrating IBM Mainframes with TCP/IP Networks" on Microsoft's World Wide Web site at http://www.microsoft.com/sna. See also "TCP/IP Connectivity in an AS/400 Environment" on Duke Communications World Wide Web site at http://www.news400.com/Education/WhitePapers/tcpip/tcpip.htm.

Most branch-based SNA gateways employ a traditional SDLC leased-line connection. SDLC is generally limited to supporting only one PU per host adapter, providing up to 254 LUs per connection. However, in the case of DLC and channel attachment connections, multiple PUs per adapter are commonplace, supporting thousands of LUs.

Primarily because of the limitations of branch-based deployment, many organizations have moved to a centralized model. On the following pages, we will look at the advantages and disadvantages of a centralized approach.


Centralized SNA Gateway Deployment

Figure 2.4 In a centralized deployment, SNA Server computers support local and remote split-stack SNA clients, server-based applications, and TN3270 emulators.

In a centralized configuration, the SNA Server computers are located near the host systems at central sites. In a typical centralized deployment, as depicted in Figure 2.4, channel-attached or high-speed token-ring-attached SNA Server computers are placed at the data center and connect to the host using SNA protocols. The centralized SNA Server computers provide split-stack 3270 and AS/400 access for local and remote desktops, which connect to the gateways using TCP/IP or another WAN protocol. Additionally, desktop- or server-based LU0 and LU6.2 applications, plus TN3270 emulators, can connect through these gateways from anywhere on the WAN.

Advantages of a Centralized Strategy

There are many advantages to following a centralized SNA gateway deployment strategy. These include using a single protocol on the LAN and the WAN; efficiently sharing host resources; easing administration; improving reliability with load balancing and hot backup; and employing high-speed host connections.

Using a Single Protocol on the LAN and the WAN

A centralized deployment model not only makes possible but presupposes the existence of an efficient WAN environment. All desktop access to host systems is across routable protocols such as TCP/IP. Of course, a centralized configuration requires higher-capacity WAN links to support the increased traffic. This deployment model will yield less-responsive client-to-server connections, yet offers faster server-to-host connections when compared to a branch-based configuration. With a centralized deployment strategy, organizations can take advantage of SNA Server's high-speed token-ring, Ethernet, or FDDI connections, as well as even-higher-speed channel attachment options.

Efficiently Sharing Host Resources

Deploying groups of SNA Server computers allows the network administrator to use features such as LU pooling, load balancing, and hot backup. These features can make host logical units (LUs) more available and host connections more reliable. This is often one of the key reasons why network managers deploy SNA Server computers centrally...

Up to 15 SNA Server computers can interoperate simultaneously in an SNA Server group, called an SNA Server subdomain. An unlimited number of SNA Server subdomains can be deployed in any one Windows NT domain. Each subdomain can contain one primary SNA Server and up to 14 backup SNA Server computers for a total of 15 SNA Server computers. The primary SNA Server computer stores the master copy of the subdomain-wide configuration file, which containsconnection (PUs/LUs) and user/group access right information. The SNA Server computers communicate with each other in two ways: (1) the primary SNA Server replicates the SNA Server configuration file (COM.CFG) to each backup SNA Server when changes are made to the configuration using the SNA Server Manager program; and (2) all SNA Server computers send multicast messages to each other to notify the other SNA Server computers of major status changes, such as server and host connection activation or deactivation.

When an efficient WAN is implemented and SNA Server computers are centrally deployed, users located anywhere on the WAN can access the same host resources on an as-needed basis. This is accomplished with an SNA Server feature called LU pooling, in which dependent LU sessions and APPC session pairs are grouped together into a pool of common resources. Pools allow groups of intermittent users to share resources efficiently. A user, APPC transaction program, LUA application, or downstream system requesting pooled resources

from SNA Server gets LU access so long as one of the pooled sessions is available. For example, 100 3270 users who need intermittent access to one session each may find that a pool of 50 3270 LUs is adequate for their needs. With proper capacity planning, pooled resources are more efficient, more flexible and easier to administer.

Easing Administration

LU pooling reduces the number of host connections required and makes better use of host administration time, which would otherwise be spent reconfiguring host PUs and line definitions as required to meet constantly changing needs. Additionally, centrally located SNA Server computers are easier to secure and manage by the central-site MIS group. This reduces the potential need for SNA expertise at remote sites.

Improving Reliability with Load Balancing and Hot Backup

LU pools and APPC session pairs can be configured across multiple central-site SNA Server computers to provide load balancing and fault tolerance. Load balancing ensures greater reliability by reducing the possibility that any single SNA Server will be saturated and performance will degrade. Fault tolerance can be provided through an SNA Server feature called hot backup. Hot backup ensures that if one central-site SNA Server computer should fail, then users can connect via another server automatically.

Employing High-Speed Host Connections

Centrally deployed SNA Server computers can easily be configured for channel attachment or high-speed LAN links to the host. Channel attachment offers the fastest throughput to a mainframe. ESCON supports up to 17 MBytes/sec over eight channels for a total bandwidth of 135 MBytes/sec, compared to 16Mbps for token ring. In many cases, a channel-attached SNA Server computer can bypass the front-end processor (FEP), minimizing the transaction response time. For AS/400 connections, SNA Server can connect via high-speed token ring or Ethernet. To best take advantage of these high-speed host connections, SNA Server is based on the scalable Windows NT Server platform and can support up to 2,000 users running up to 10,000 concurrent sessions across up to 250 concurrent host connections.

Disadvantages of a Centralized Strategy

There are disadvantages to centrally deploying SNA gateways. These include slower response times when large numbers of users connect across the WAN from branch-office to centralized SNA Server computers; and greater WAN bandwidth requirements as a result of multiple client-to-server sessions between SNA desktops and SNA Server.

In a centralized model, the network manager will likely turn on at the workstation the Nagle (see the discussion of the Nagle TCP/IP compression algorithm in the following section on the distributed deployment model)TCP/IP compression algorithm, which is the default for SNA Server's client-to-server communications and Windows NT Server's TCP/IP. This improves mission-critical client-to-host traffic. Yet, Nagle will slow down other essential traffic—that flowing between the PC and local LAN servers, such as file and print access. In contrast, a distributed deployment allows the network manager to configure Nagle "on" and achieve maximum benefit for both local LAN server access and PC-to-host connectivity. This is because in a distributed deployment all traffic is considered "local" between the workstation and the LAN file server or SNA Server computer. Therefore, workstations will have similarly good (the best overall) response between both client-to-server and client-to-host connectivity.

Microsoft has recognized the disadvantages of centrally deployed SNA gateways. In order to correct these issues, Microsoft has produced an alternative deployment strategy—the distributed model. Distributed deployment combines the advantages of the branch-based and the centralized deployment models without the disadvantages of either.


Distributed SNA Gateway Deployment

Figure 2.5 SOGA offers a new distributed deployment model that makes better use of available WAN bandwidth than branch-based or centralized configurations.

The distributed deployment model presupposes the existence of a WAN environment consisting of a routable protocol such as TCP/IP, IPX/SPX, or Banyan VINES. We previously discussed the advantages and disadvantages of following a branch-based or centralized strategy to provide client-to-host connectivity in a WAN environment. Those problems can be overcome by following a distributed deployment. The distributed approach combines the branch-based and centralized models to achieve a best-of-both-worlds solution without any of the negatives represented by either model alone.

In a distributed configuration, the SNA Server computers are located both centrally near the host systems and also in the branch offices near the end users. One of the key benefits of a branch-based deployment is that it isolates the heavy client-to-server traffic to a local ring or segment. The SNA Server computers are deployed in the central locations so they can use the latest in channel-attachment technology or high-speed LAN connections. Centrally locating the SNA Server computers allows for isolation of the SNA protocols to the data center or backbone LAN.

The central-site SNA Server computers "distribute" their host links for use by the branch-based SNA Server computers. The branch-based SNA Server computers connect to the host systems by sharing the distributed physical connections of the central SNA Server computers. Connections between branch and centralized SNA Server computers are via TCP/IP, IPX/SPX, or Banyan VINES. This new server-to-server capability is a feature released in Service Pack 1 for SNA Server 2.11 called the distributed link service. At the heart of the Distributed link service is a new host link service called the Distributed Link Service (DLS). See Figure 2.5 for a depiction of a typical distributed deployment topology.

Configuring the Distributed Link Service

Configuring the distributed link service is a two-step process. Step 1 is performed on the central-site SNA Server computer. Step 2 is performed on the branch-based SNA Server computer.

Central SNA Server Configuration

Figure 2.6 The SNA Server administrator distributes a link service by simply choosing the "Distribute"checkbox in the link service property page. This makes the link service available for use by a branch-based SNA Server.

In the first step, the SNA Server administrator copies one or more host link services using the SNA Server Setup program. This can be done at the time SNA Server is first installed or later by re-running setup.Host link services are the interfaces between SNA Server's protocol engine (the node) and the host link adapters, such as a channel attachment device or the token-ring adapter depicted in our example. See Figure 2.6.

In order to make the central-site host link adapter available to a branch-based SNA Server, the SNA Server administrator must "distribute" the central-site link service. This is done by choosing the "Allow Link Service to be Distributed" checkbox on the link service property page as shown in Figure 2.6. The link service is designated as distributed by a "(D)" in the Installed Link Services list box. Once distributed, the central SNA Server link service and underlying host link adapter are available for use by the branch-based SNA Server. The only exception is if a link service is already in use when the administrator distributes it, then in order for this change in status (from "undistributed" to "distributed") to take effect, the link service must be stopped and re-started. The SNA Server administrator can do this from a Windows NT command prompt by typing "net stop <service name>," then "net start <service name>." In the example, the DLC 802.2 Link Service #1 on the central SNA Server has been distributed for use by a branch SNA Server.

C:\>dlsstat \\central1
SnaDlc1 (Token-ring, SAP 0x04) is used by:
SnaDlc2 (Token-ring, SAP 0x08) is used by:
C:\>

Figure 2.7 DLSstat provides the SNA Server administrator with the status of any distributed link service located anywhere on the network.

To determine if a central-site link service is distributed and available, the SNA Server administrator can use the Distributed Link Service Status (DLSstat) utility. This utility is accessible at a Windows NT command prompt by typing

dlsstat \\<server name>.

If this command is typed on the same machine as the central site distributed link service, then the SNA Server administrator can omit the server name in the command.

The output will look like that depicted in Figure 2.7. In the example, the central-site SNA Server is named "Central1". That server has two link services distributed, one named "SnaDlc1" and one named "SnaDlc2." Both are available for use by any SNA Server computer on the network.

C:\>dlsstat \\central1
SnaDlc1 (Token-ring, SAP 0x04) is used by:
    \\branch1
SnaDlc2 (Token-ring, SAP 0x08) is used by:
C:\>

Figure 2.8 DLSstat is used to list the name of the branch-based SNA Server computers currently using link services on a central site SNA Server computer.

DLSstat supports the use of NetBIOS name, IP alias, and IP address (e.g. "\\123.33.33.133") to locate an SNA Server computer anywhere on the network. It can also be used to provide a list of the central link service each branch SNA Server is using.

In the example, the branch-based SNA Server named "Branch1" is using the distributed link service named "SnaDlc1" on the central-site SNA Server named "Central1." The parenthetical in the DLSstat output represents the central site "link service title" or comment. The SNA Server administrator can modify this comment to make it more descriptive.

The link service is configured at the central SNA Server computer using SNA Server Setup. This includes assigning a local service access port (SAP) for the SNA Server computer's host link adapter. In the example, the SNA Server administrator would configure the local SAP for the token-ring adapter used by the DLC 802.2 Link Service #1 on the central-site SNA Server. There is nothing to configure in SNA Server Manager. In fact, if all link services of a central-site SNA Server computer were distributed for use by branch-based SNA Server computers, then the central-site SNA Server Managerand SnaServer service would never need to be started. Distributed link services are provided on a first come, first served basis. For example, when SnaDlc1 on Central1 is being used by SnaRem1 on Branch1, then no other SNA Server can use SnaDlc1. Because the same distributed link service cannot be used by multiple SNA Server computers simultaneously, the SNA Server Manager is designed to hide a distributed link service. This avoids the confusion where an administrator might attempt to configure the connection for use by both the branch and the central SNA Server. In the example, all that is required to run on Central1 are the SnaBase, SnaDlc1, and SnaDlc2 services.

The SNA Server node communicates to the host system through the Dynamic Module (DMOD), a service layer that provides inter-object messaging throughout SNA Server. The SNA Device Interface Specification (SNADIS) application programming interface (API) provides a device-independent layer between the host link services and the DMOD. Many different host link services are available for SNA Server, one for each independent hardware vendor's (IHV) link driver, including: 802.2, DFT, twinax, and numerous SDLC, X.25, and channel adapters. The SNADIS API allows SNA Server to support multiple adapters produced by many vendors without affecting the architecture of the node or other components of SNA Server.

Figure 2.9 The central SNA Server, Central1, has two distributed link services installed--SnaDlc1 and SnaDlc2. These link services are made available to the node on the branch SNA Server, Branch1, via the distributed link service. The connection between the two computers is via the SNA DMOD.

The connection between two distributed link services, one on a central-site SNA Server computer and one on a branch-based SNA Server computer, is made using substantially the same mechanism as that used for SNA Server client-to-server communications. The link is established and maintained by the two DMODs on each SNA Server computer, as shown in Figure 2.9. This is why the distributed link service supports the same routable WAN protocols as the client—TCP/IP, IPX/SPX, and Banyan VINES.

Branch SNA Server Configuration

Figure 2.10 The SNA Server administrator installs a distributed link service, SnaRem1, on the branch-based SNA Server computer, Branch1, and configures it to use one of the target central-site SNA Server computer's distributed link service—in this case, SnaDlc1 on Central1.

The second step in configuring the distributed link service is performed on the branch-based SNA Server computer. The SNA Server administrator installs one or more distributed link services using the Insert Link Service menu option. The SNA Server administrator enters the link service name of the central-site SNA Server computer in a configuration dialog, choosing the link type, and entering the central-site SNA Server computer's distributed link service as shown in Figure 2.10. An alternative central-site link service can also be entered. The remote link services and alternative link services edit boxes will accept any information. Ther server name and link service name that the SNA Server administrator enters are not validated by SNA Server. This allows the administrator to configure distributed link service to use link services that have yet to be installed on a central-site SNA Server computer. See Figure 2.10.

The SNA Server administrator must match the type of link service on the branch-based SNA Server with the central SNA Server link service. In the example, the SnaDlc1 on Central1 is a token-ring 802.2 link service; therefore, the SnaRem1 on Branch1 must be set to link type of token-ring 802.2. Next, the connection over the newly installed SnaRem1 distributed link service must be configured using the SNA Server Manager on the branch-based SNA Server computer. SNA Server Manager can be run locally on branch-based SNA Server computers or remotely on any other Windows NT Server or Windows NT Workstation computer. The connection properties for the connection that uses SnaRem1 must match the host PU configuration or line definition on the host system. See Figure 2.11. For the configuration procedure see SNA Server Manager Help.

Figure 2.11 The SNA Server administrator configures the token-ring 802.2 connection, which uses the SnaRem1 distributed link service, as if it were a local connection.

The administrator configures the distributed link service connection as if it were a local connection according to the host link type and media type of the target central-site SNA Server link service. In the example, the connection is to a host mainframe. Therefore, the administrator must define the remote network address of the host's token-ring adapter and local node identifier (ID BLK and IDNUM parameters) configured in the PU definition in VTAM®. For AS/400 connections, consult the AS/400 administrator for special configuration issues.

Configuring for Load Balancing

The SNA Server administrator can configure a branch-based SNA Server to connect through multiple central SNA Server computers to achieve load balancing. Load balancing can reduce the likelihood that any single SNA Server or central-site link service will become overloaded and fail by equalizing the load across multiple connections and servers. This is done by entering multiple server and service names, separated by a semicolon, in the remote link services configuration dialog. The distributed link service on the branch-based SNA Server computer is designed to connect to a central-site distributed link service according to a random selection from the link services listed in the remote link service field of the distributed link service dialog, as shown in Figure 10. This random selection is intended to provide a degree of load balancing.

Configuring for Fault Tolerance

The SNA Server administrator can configure a branch-based SNA Server to connect through one or more central SNA Server computers. The SNA Server administrator can configure the branch-based SNA Server for load balancing by entering multiple server and service names in the remote link services edit box, as shown in Figure 2.10. Should a central SNA Server computer or link service go down, a branch-based SNA Server computer can immediately reconnect to the target host system through another central-site SNA Server or link service.

Advantages of a Distributed Strategy

In a distributed deployment, the centralized SNA Server computer distributes its host data links for use by the branch-based SNA Server computer, creating an effect similar to PU pass-through. Although SNA Server does not combine individual LUs and PUs into the same network packet, because the SNA architecture prohibits putting multiple request/response units (RUs) in a single PIU (path information unit), the WAN transport will do this by default. In the example, Branch1 connects to Central1 across a routed TCP/IP WAN. If WAN bandwidth is a constraint (e.g., the WAN is frequently congested), then Windows NT Server will aggregate the server-to-server traffic using the Nagle TCP/IP compression algorithm. This will cause fewer, fuller, TCP buffers to be sent between SNA Server computers. This reduces the ratio of TCP/IP overhead bytes to data payload. The net result is better use of available WAN bandwidth, which should ultimately result in better response times during periods of high WAN usage. The downside is that in order for such aggregation of messages to occur, there must be a slight delay in transmission of some segments, which can cause a decrease in response times. As such, network managers should disable the Nagle algorithm if bandwidth is not a constraint. .. For more information see the SNA Server Knowledge Base article Q138831. The following may be helpful in enhancing communication on SNA Server:

  • Packet Size Compared to Centralized Model. ..Both the centralized approach and the distributed approach use the SNA Server client-server transport for the connection across the WAN. Therefore, they both produce the same overhead per message. However, there is less traffic (i.e. lower bandwidth use) across the WAN as a result of using the distributed link service, because of the reduced number of messages. Client-to-server connections produce many more messages than server-to-host connections.
  • Local Response to Host Polls Reduces Traffic on WAN. Remote hardware controllers must respond to each poll from the host. This can create extra traffic across a WAN that supports the remote controllers via DLSw or RFC 1490. In the case of a distributed SNA Server deployment, the polling does not go beyond the central site. The distributed link service, which runs on the central server, handles all link-level traffic on behalf of the remote SNA Server computers, including responding to host polls. The result is a marked reduction in WAN traffic when compared to remote controllers using a DLSw or RFC 1490 WAN.
  • Max BTU and TCP/IP Packet Size. The central-site SNA Server DMOD (see Figure 2.9) treats the distributed link service as if it were any other link service. The node will split up the data into the size specified as the maximum BTU (basic transmission unit) for the connection over which the data is sent. Of course, when a message is smaller than the BTU size, it will be transmitted complete. This works well with most DLC types used for the majority of distributed deployment environments—where network managers will employ mostly channel-attachment and high-speed token-ring DLC host links. In the typical scenario, the BTU size will be larger than the WAN packet size. In the case of some other DLC types (e.g. SDLC) where the BTU size may be less than the WAN packet size, the distributed link service seems to present a less-than-optimal solution. SNA Server does not alter the message flows to combine multiple messages together before transmission. To do this would have an adverse effect on perceived user response times. When the WAN is slow or becomes congested, then even SDLC and other small BTU link types will perform better over a distributed link service. This is because the underlying WAN protocol will combine multiple RUs.
  • Configuring the KeepAlive for TCP/IP Links. In a low-bandwidth routed IP environment, the SNA Server administrator can configure SNA Server and Windows NT Server to make optimal use of limited bandwidth. First, SNA Server can be configured for "on demand" activation, where the connection will only be activated if a user attempts to open a session over the connection (and the connection will be dropped when the user ends the session). Second, the KeepAlive time interval can be raised to reduce the number of messages sent to keep an unused link active. The default is 60 seconds. Both ends will send this KeepAlive to the other end to check that the other side is still operating. The KeepAlive parameter is in the Windows NT Server Registry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\SnaBase\Parameters\SnaTcp\KeepAlive:REG_SZ:"YES" | "NO".

    The KeepAlive parameter can be used to disable TCP's own KeepAlive (SO_KEEPALIVE option) messages. The default value is "YES" (TCP KeepAlive is enabled). By setting the KeepAlive to "no", which tells the IP stack to keep the connection open, and the WatchDogTimeout to "no limit," the SNA Server administrator can keep the distributed link connection active even when there is no longer any actual traffic. In this case, only the server-to-host connection remains active. This is useful in WAN environments composed of ISDN or X.25 connections (in which cost is associated with time connected) between branch and central SNA Server computers.

  • Configuring the WatchDogTimeOut for TCP/IP Links. The SNA Server administrator can control the KeepAlive message rate by modifying the WatchDogTimeOut variable. This variable affects the time-out interval used with TCP/IP. When activity ceases across an established session (that is, when no messages are being sent), the local system waits the specified interval and then sends a message to see if the remote system responds. If the remote system does not respond, the local system closes down the session. A local system uses the local value regardless of the value on the remote system. The SNA Server administrator can decrease this number to create a faster response to failures within a TCP/IP network, or increase this number to minimize overhead on a TCP/IP network on which system failures are infrequent. The range is 30-3600 seconds (3600 seconds equals 1 hour). If this variable is not set, it defaults to 60 seconds. The WatchDogTimeOut parameter is in the Windows NT Server Registry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\SnaBase\Parameters\WatchDogTimeOut:REG_DWORD:number.

The potential impact of having a very high WatchDogTimeOut value in a distributed link service configuration is that it would take the branch server a long time to determine that the host connection has gone away if there's no other traffic. You can set this value as high as two hours, which would mean that the standard TCP/IP watchdog timeout takes over (default is 60 minutes). In that case, the branch-based SNA Server computer would notice the dropped connection (within about a minute) when it next attempts to send data to the host.

Network Simplicity by using a Single Protocol on the LAN and the WAN

Another benefit of the distributed link service is that it provides network simplicity by allowing the network manager to support merely one LAN and WAN protocol. No SNA protocols need to be routed or bridged across the WAN. No expensive DLSw routers need to be employed. Any software-based or hardware-based router or bridgecapable of passing TCP/IP, IPX/SPX, or Banyan VINES will support distributed link service. This significantly simplifies wide-area network management...

Broad Support from Industry-Leading Internetworking Vendors

A distributed deployment approach presupposes the existence of a WAN environment. Because the branch-based SNA Server computers rely on the WAN services provided by leading internetworking vendors, the distributed link service will work over all existing and future WAN technologies, including leased lines, X.25, frame relay, and ATM networks. This means greater flexibility for organizations seeking to better use or consolidate their network infrastructure.

Efficient Sharing of Host Resources through Load Balancing

The branch-based SNA Server computers can connect to the host via multiple centralized SNA Server computers, load-balancing between the central-site SNA Server computers at connect time. Pools of LUs can span multiple connections on one or more SNA Server computers. Typically, each remote site will consist of a single subdomain. In that subdomain there will likely be one or two SNA Server computers. If two computers are used, then the SNA Server administrator can configure a pool that spans connections on both branch-based SNA Server computers. Not withstanding how many servers are at the branch site, a pool of LUs can also span multiple distributed link service connections across different central-site SNA Server computers. When a pool is spread across PUs on the same node, the node will allocate all the LUs from the first PU before allocating any from the second. This prevents the node from activating several on-demand connections and allocating a few LUs from each when only one is actually needed. When a user requests a session in the LU pool, the load will be balanced across multiple connections, multiple remote servers, and multiple central-site servers. Load balancing is one way to ensure greater fault tolerance. The better the load is balanced evenly across multiple server-to-host links, the greater likelihood that no one connection or server will fail. Distributed link service load balancing even works with dedicated LUs. The SNA Server administrator can assign each user a separate LU pool containing at least two sessions that are bound to different SNA Server computers or connections.

Greater Reliability through Configuring Fault Tolerance across Multiple Central-Site SNA Server Computers

Reliability is built into the distributed link service. In a distributed deployment, a branch-based SNA Server computer communicates with the central-site SNA Server via a TCP/IP connection, which eliminates DLC time-out problems associated with traditional SNA encapsulation methods such as DLSw. Additionally, the host link services on the central-site SNA Server computer provide local acknowledgment to the host system, assuring that host connections do not time-out. The SNA Server administrator can configure further levels of fault tolerance.

First, the SNA Server administrator can configure two or more branch-based SNA Server computers with like resources using LU pooling in the case of mainframe connections or the same local LUs in the case of AS/400 connections. If one server goes down, then the other server(s) will operate in hot backup mode to ensure continued host access.

Second, the SNA Server administrator can configure multiple distributed link service connections to two or more central-site servers, ensuring fault tolerance should a central-site SNA Server computer fail.

Third, the SNA Server administrator can configure branch-based SNA Server computers to connect via dial-up SDLC, leased-line SDLC, and X.25 networks as a backup. Fourth, the SNA Server administrator can configure branch-based clients to connect to central-site SNA Server computers directly, should the branch office servers become unavailable.

Flexible Administration through Optional Security and Host Management of Branch-Based SNA Server Computers
  • Extra level of flexible security. By default, no added security is applied to server-to-server communications in a distributed deployment. Any branch SNA Server computer can by default access a distributed link service on a central SNA Server computer using an anonymous logon. This is true even though the central-site Windows NT Server computer is configured to deny guest logins. When a local link service on the central-site SNA Server is distributed, it is shared to the world just like an "everyone" file or printer share. However, the SNA Server administrator can restrict access to a central-site distributed link service by adding the following Windows NT registry entry: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\SnaBase\Parameters\DenyAnonymousLogon:REG_DWORD:1.

    This SnaBase registry parameter disables anonymous logons. The default value is 0 for anonymous logons allowed. If the anonymous logon is disabled on the central SNA Server computer, then all branch server distributed link services must be configured to run under a user account, not local system, in order to gain access to the shared central-site link service. The user account of the branch-based SNA Server computer has to be one that is recognized as valid by the central server as capable of running the distributed link service with local system authority on the branch-based server. It is essentially verification of whether the peer SNA Server computer is truly a peer. The network manager can verify that a user who is logged on to the remote system does not have any access by typing "net view \\<server name>" from the branch-based SNA Server computer. ..

    • Administration of distributed link services over Internet connections. The distributed link service can be configured for use across an intranet or the Internet. To avoid having to resolve the central-site SNA Server computer's NetBIOS name or IP alias ("Central1" in our example), the administrator can use "\\<server IP address>\<link service name>."
    • Management of branch-based SNA Server computers from a centralized host system. Since the central-site SNA Server computers provide the equivalent of PU pass-through service for the branch-based SNA Server computers, the host operator sees each branch-based server as a PU and can manage the branches via standard NetView alerts and RunCmds.
Full SNA Application Support

Unlike other popular SNA-over-WAN solutions such as TN3270 and AnyNet, the distributed link service is not limited in SNA functionality. Each branch-based SNA Server computer provides full SNA access for the local PCs, including PU2.0, PU2.1, and APPN® LEN service, as well as LU0, LU1, LU2, LU3, and LU6.2 support. Both mainframe and AS/400 access are supported concurrently. In some cases, host applications initiate a transaction across a connection. These include many APPC-based host-to-PC file transfer solutions. At the same time, the host connection might prohibit a continuously open link. As such, it is important that the SNA gateway solution allow for flexible and cost-effective connections between central-site host systems and remote sites. The distributed link service supports host-initiated connections for 802.2 distributed link services. This is useful for organizations that use ISDN and for other networks where costs are based on connection time.

Multi-function Server Availability in Branches

Because of the scalability and multitasking capabilities of the Windows NT Server operating system, a single branch-based server computer can function as an SNA gateway, file and print server, e-mail server, database server, systems management server, and intranet or Internet server. Because SNA Server is an integrated component of the Microsoft BackOffice™ suite of products, host data can be shared with other BackOffice applications efficiently and securely.


High-Performance SNA Server Configurations

A key component of SOGA is a high-performance SNA gateway. One indicator of performance is the availability of high-speed, server-to-host connection methods. SNA Server supports powerful channel-attachment options available from leading host connectivity vendors: Amdahl, Barr Systems, Bus-Tech, Cabletron, Computerm, Dr.Materna, and Polaris Communications. Today, many organizations seek to replace their old IBM front-end processor and controller gear with new, open channel-attached solutions to gain better performance and save on administration and maintenance costs. Based on the latest Intel® and RISC processors, channel-attached SNA Server computers provide greater speed, better scalability, more flexible upgradeability, and, most importantly, significantly better cost-effectiveness than traditional dedicated hardware devices. Channel-attached SNA Server computers are the optimal platform for deploying the distributed link servicein mainframe environments.


SOGA Channel-Attachment Technology

SNA Server supports two channel-attachment technologies—Bus & Tag and ESCON (Enterprise System Connection). Both offer speed improvements over high-speed token-ring, Ethernet, and FDDI.

Bus & Tag Provides Greatest Flexibility

Bus & Tag channel attachment uses parallel copper cable and offers speeds up to 4.5 megabytes per second. This is a significant improvement over high-speed token rings, which only provide16 megabits per second.

SNA Server's channel attachment capability provides deployment flexibility because of the many channel vendors offering solutions. The hardware vendors that offer Bus & Tag products that comply with SOGA include Barr Systems, Bus-Tech, Cabletron, Computerm, and Polaris Communications. Contact information and white papers for these companies is located in the SNA Server Companion Product Catalog at http://www.microsoft.com/sna.

ESCON Provides Greatest Performance

A second channel attachment option is ESCON (Enterprise System Connection). ESCON uses standard fiber cable and increases the speeds offered by channel attachment up to 200 megabits per second (roughly 17 megabytes per second). Currently, Polaris Communications has released a PCI ESCON solution for SNA Server. Amdahl, Bus-Tech, and Dr.Materna have also announced support for SNA Server ESCON products.

SNA Server takes advantage of these high-speed channel attachment options by supporting up to 250 concurrent host connections. Each channel device can support multiple host PUs. SNA Server supports up to 5,000 concurrent users running up to 15,000 concurrent sessions.


Advantages of a High-Performance SNA Gateway

Deploying SNA Server to provide host connectivity for desktops and server PCs offers many advantages, including: flexibility to perform multiple functions; efficient use of host resources; support for a virtual LAN over SNA-only data links; flexible network administration; broad support for required SNA applications; and integration of BackOffice-based applications with host data.

Flexibility to Perform Multiple Functions

SNA Server performs multiple functions that help the network integratedisparate desktop, LAN, and host systems.

  • SNA Server can function as a traditional split-stack SNA gateway. It can be configured to support LU0-LU6.2 applications running on a broad range of client platforms and across a broad range of LAN protocols. Figure 2.12 depicts SNA Server's breadth of desktop and LAN protocol coverage.

Figure 2.12 SOGA relies on flexible SNA gateway solutions such as SNA Server. SNA Server has broad support for multiple desktop operating systems and popular LAN protocols.

  • It can function as a TCP/IP-to-SNA protocol converter, supporting both TN3270 emulators and split-stack SNA clients.
  • Additionally, SNA Server can be deployed as a platform for secure, high-performance server-to-host LU6.2 applications, such as high-speed file transfer or host database access. For example, SNA Server can function as an FTP server for TCP/IP clients uploading or downloading files to host systems. The FTP-to-AFTP (APPC File Transfer Protocol) gateway service converts the FTP (TCP/IP) commands to APPC commands. The protocol conversion takes place on the SNA Server computer rather than on the host system. The result is simple file transfers to and from host systems without the complexity or cost of running TCP/IP on the host. (This solution requires IBM APPC Application Suite for MVS, VM or OS/400®.)

An Efficient Use of Host Resources

An SNA gateway approach allows the host to be configured with only native SNA. The workstations can be configured with only TCP/IP or another popular LAN protocol. The SNA gateway approach allows PU-sharing, reducing the number of PUs required on the host; therefore, the host only needs to poll the SNA gateway. With other host-access models, hundreds of end-user definitions are typically stored in resident memory on the host system and FEP, consuming expensive host resources. By assigning host sessions to individual user accounts on the SNA gateway machine, SNA gateways save memory and CPU cycles on the host system.

Support for a Virtual LAN over SNA-only Data Links

Another option with SNA Server is the capability of creating a virtual LAN over SNA-only host links. This option is most often used in traditional branch-based configurations where no WAN exists between remote sites. Remote offices can be linked together across APPC LU6.2 connections established between SNA Server computers. The feature is called SNA Remote Access Service. The effect is to create a slow-link WAN that interconnects otherwise isolated branch-office LANs. This solution is ideal for providing communication between other Microsoft BackOffice or Windows NT Server-based applications that would be isolated in an SNA-only WAN environment. For example, post office-to-post office communications between remote Microsoft Exchange Server computers can be accomplished using SNA Remote Access Service.

Flexible Network Administration

When all host-bound traffic is concentrated through SNA Server, the network manager can use performance-monitoring, event-logging, and tracing capabilities of the Windows NT Server platform more effectively to manage desktop-to-host traffic. An individual desktop problem is easy to work around by simply assigning a new LU while the administrator performs debugging at the server without interrupting other users or restarting the server.

Even though SNA Server provides the capability for greater server-based network management, it is not uncommon for large enterprises to perform all or most of their network management on IBM mainframe systems, using tools such as IBM NetView. SNA Server supports NetView to make centralized network management simpler.

SNA Server can forward to NetView custom alerts and informational messages from any Windows NT Server in the domain, using an optional NVAlert service. All events logged to the Windows NT Event Log can be viewed by the host NetView console operator. This allows for central monitoring of distributed server-based solutions.

Yet, the SNA Server NVAlert service only informs the NetView console operator of the problem. It does little good to know of a problem if one cannot act on the information. This is why SNA Server installs a NetView RunCmd service on the Windows NT Server computer, which extends access to the Windows NT command line for the host NetView console operator. The NetView RunCmd service allows the NetView console operator to directly control all functions of the Windows NT Server on which SNA Server is running.

Broad Support for Required SNA Applications

SNA Server uses industry-standard SNA protocols for connecting to IBM mainframe and AS/400 computers. This allows host systems to run the native SNA protocols for which they have been optimized. At the same time, SNA Server supports client emulators and server-based APPC applications across all popular LAN protocols, including TCP/IP, IPX/SPX, Banyan VINES, and Microsoft Networking. This allows desktop and server computers to run the protocol that has been chosen by the network manager. With SNA Server, network managers can immediately begin to integrate their disparate systems, while planning their next-generation information solutions.

Figure 2.13 SNA Server's client/server architecture provides support for the required SNA APIs on popular client platforms and the Windows NT Server operating system.

SNA Server is designed using a client/server model. On every client computer there is an SNA Server module that provides support for a full range of application programming interfaces and allows for the protocol-neutral LAN connection. On the SNA Server computer there are the same broad range of APIs for basing server-to-host solutions. See Figure 2.13 for a view of the SNA Server client/server architecture.

Integration of BackOffice-based Applications
with Host Data

Based on the Windows NT Server operating system platform, a channel-attached SNA Server computer can also be shared with other functions, such as file and print server, e-mail server, database server, systems management server, and Internet or intranet server. Because SNA Server is an integrated part of Microsoft BackOffice, it acts as glue to bond BackOffice applications and services with host systems and data.

Microsoft Windows NT Server

Multiple SNA Server computers linked using SNA Remote Access Service allow Windows NT Server computers to share files and security validation information.

SNA Server supports Windows NT Server another way through its NetView Services, which allow host administrators to execute any Windows NT command line from an IBM NetView console. Other capabilities of this feature set make it possible to forward any Windows NT event log message to NetView and permit LAN administrators to view NetView performance data on any Windows NT Performance Monitor. NetView Services allow organizations to integrate Windows NT Server-solutions, such as SNA Server, into their existing NetView centralized network management systems.

Microsoft SQL Server

SNA Server ships with a copy of a StarSQL ODBC-to-DRDA™ driver. This driver allows the SNA Server Manager to integrate host data (DB2® for MVS, DB2 for VM, DB2/400 for OS/400) with Microsoft SQL Server™. Organizations no longer need to license and deploy expensive, single-purpose SQL-to-host database gateways to connect host databases with desktops and servers. Using ODBC-enabled tools such as Microsoft Query, data manipulation and presentation can be performed on the desktop with popular applications such as Microsoft Excel.

For truly mission-critical solutions, third-party products that are based on SNA Server provide DB2-to-SQL Server data replication. The vendors currently supporting SNA Server-based solutions include: ExecuSoft, ShowCase, and DataMirror.

Microsoft Systems Management Server

SNA Remote Access Service supports all functions of Microsoft Systems Management Server (SMS). This allows a network manager to use the SMS software distribution, remote control, and other management capabilities across an enterprise using only SNA host links, such as dedicated leased-line SDLC connections.

Microsoft Exchange

SNA Remote Access Service enables post office-to-post office connectivity over SNA networks. This allows organizations to deploy Microsoft Exchange in sites that would otherwise be cutoff from server-based corporate e-mail.

PROFS and SNADS gateways, specifically designed to function with SNA Server, link host e-mail and scheduling to Microsoft Exchange Server. This provides organizations with the capability to migrate legacy e-mail and scheduling users to the latest server-based messaging technologies.

Microsoft Internet Information Server

The Microsoft Internet Information Server includes an Internet Database Connector that, teamed with the StarSQL ODBC/DRDA driver, can be used to create forms-oriented data links between IBM DB2 databases and the Internet or intranet. This allows organizations to publish secure, host-based data directly to their Web servers. Additionally, publishers can provide hyperlinks from Web pages to files that reside on IBM mainframes or AS/400s using SNA Server's FTP-to-AFTP gateway.


Efficient Wide-Area Network Use

SNA gateways rely on the existence of an efficient wide-area networking infrastructure based on hubs, bridges, and routers to provide internetworking services that link branch and central sites. WAN-attached branches require a cost-effective solution for accessing frame relay, leased-line, or ATM networks. Additionally, many legacy devices such as automated teller machines, bisync printers, and ASCII terminals still need to be connected to host systems but cannot make effective use of the WAN. SOGA completes many WAN solutions by linking these legacy devices to the data center through the same wide-area network.

Branch-based SNA gateways can use WAN technologies, such as DLSw, Frame Relay, ATM, X.25, and leased-line SDLC. Centralized and distributed SNA gateways require a TCP/IP-based or other WAN The distributed link service supports the following routable protocols: TCP/IP, IPX/SPX, and Banyan VINES. In all cases, an efficient WAN is provided by leading internetworking vendors. SOGA merely offers the means to make better use of the existing WAN environment.


SOGA Supports Popular WAN Connection Options

Leased-line SDLC

Extending the economic and technical usefulness of existing investments in networking infrastructure is one of SOGA's strong points. Most organizations have existing leased-line SDLC connections that can be used with branch-based deployments, as well as with distributed deployments as backup connections. See Figure 2.2 for a depiction of a traditional branch-based deployment leveraging existing investments in leased-line SDLC connections.

SNA Server supports the following vendors' SDLC adapters:

  • Attachmate® (DCA™)
  • Barr Systems
  • Cirel Systemes
  • Digi International
  • Eicon Technology
  • IBM
  • MicroGate
  • Passport Communications
  • Sangoma Technologies
  • SAT Dpt Atlantis

X.25 Packet Switched Networks

Organizations make use of existing X.25 private or public Packet Switched Networks (PDNs) to link branch-based SNA gateways with central-site host computers. These X.25 connections are primarily used in branch-based deployments to link remote SNA Server computers with central-site host systems.

In a distributed deployment model, X.25/QLLC connections can be used as a means to provide fault tolerance in cases of general WAN failure. See Figure 2.2 for a depiction of a traditional branch-based deployment leveraging existing investments in X.25 PDNs.

SNA Server supports the following vendors' X.25 adapters:

  • Attachmate (DCA)
  • Barr Systems
  • Cirel Systemes
  • Digi International
  • Eicon Technology
  • IBM
  • MicroGate
  • Passport Communications
  • Sangoma Technologies
  • SAT Dpt Atlantis
  • SpartaCom S.A.

Data Link Switching

One of the most popular methods for integrating SNA and TCP/IP networks is to use router-based DLC encapsulation within IP to extend SNA from the branch offices to the central site. An industry standard called Data Link Switching has emerged as the open, interoperable way to accomplish this integration. Under

SOGA, the branch-based SNA Server computers that connect to the host using the DLC protocol often rely on the DLSw support in routers to transmit the SNA traffic to the central-site LAN. See Figure 2.3 for a depiction of a branch-based configuration using DLSw.

Frame Relay

RFC1490 is emerging as an industry standard for routing DLC traffic over frame relay networks. Implemented as a software option in the branch-based router or FRAD, RFC 1490 picks up DLC traffic from the branch LAN and passes the SNA traffic through one or more virtual circuits across the frame relay network to the central site. This capability in routers and FRADs is a natural complement for branch-based deployments of SNA Server computers. See Figure 2.3 for a depiction of a branch-based configuration using frame relay.

Additionally, a central-site SNA gateway could leverage frame relay to connect the branch-office LANs with the central-site LAN. Frame relay is also an essential component of a distributed deployment configuration. Branch-based SNA gateways can communicate with the central site over a frame relay WAN. See Figures 2.4 and 2.5 for depictions of a frame relay WAN used in centralized and distributed deployment models respectively.

Asynchronous Transfer Mode

Centralized deployments can use an ATM WAN to connect branch LANs with central-site LANs. The branch-based desktops connect to the centrally located SNA Server computers across the ATM WAN. ATM can also be used in a distributed deployment configuration to link remote SNA Server computers in branch offices to SNA Server computers located near host systems in central offices. See Figures 2.4 and 2.5 for depictions of a WAN using ATM technology to deploy a centralized and distributed configuration respectively. See Figure 2.3 for a depiction of a branch-based configuration using ATM.

TN3270

The TN3270 standard is gaining popularity as a way to access 3270 applications on IBM mainframes over a TCP/IP network. This approach has the same attractiveness as the distributed link service: the enterprise network can be entirely based on TCP/IP with no DLC tunneling or encapsulation. In addition to split-stack SNA client support, SNA Server can also act as a TN3270 server, connecting to the mainframe via SNA protocols.

A channel-attached SNA Server can act as a centralized TN3270 server, providing a more complete TCP/IP-to-SNA off-load than the IBM 3172 controller. SNA Server supports TN3270, TN3287, and TN3270E, as well as split-stack TCP/IP clients for LU0 and LU6.2 applications. Other TCP/IP-to-SNA gateways support only the base TN3270 capability. For more information see "Integrating IBM Mainframes with TCP/IP Networks" on Microsoft's World Wide Web site at http://www.microsoft.com/sna.


Chapter 3 SNA Server Support

This chapter explains how SNA Server works within SNA networks. The following information is included:

  • A summary of the types and number of SNA sessions supported by SNA Server.
  • A list of the SNA commands supported by SNA Server. This section also shows the type of SNA sessions in which the commands flow.
  • The transmission service (TS) and function management (FM) profiles supported by SNA Server.
  • A list and explanation of the five categories of SNA sense codes generated by SNA Server. This section also describes logical unit (LU) type 6.2-specific sense data.

For specific information about an application programming interface (API) supported by SNA Server, see the programmer's guide for that API:

  • Microsoft SNA Server APPC Programmer's Guide
  • Microsoft SNA Server CPI-C Programmer's Guide
  • Microsoft SNA Server LUA Programmer's Guide


SNA Session Support

This section lists and explains the types and numbers of SNA sessions supported by SNA Server. For more information about the capacities of SNA Server, see the Microsoft SNA Server Administration Guide.


LU Support

The SNA Server node can support as many as 15,000 sessions.

When using LU type 6.2, an SNA Server LU can be either the primary logical unit (PLU), or the secondary logical unit (SLU). The partner LU can reside in a type 2.1 node, within an upstream type 5 node, or within the SNA Server node itself.

When using LU type 0, 1, 2, or 3, an SNA Server LU is always an SLU, and the partner LU in an upstream type 5 node is always the PLU. With LU type 0, session-level cryptography is supported, within certain limits, on the Request Unit Interface (RUI). Session-level cryptography is implemented through CRV requests; the RUI application(s) must perform all necessary processing. For details about the limits to session-level cryptography and about the processing to be carried out by the RUI application(s), see the Microsoft SNA Server LUA Programmer's Guide. With all interfaces other than RUI, CRV requests are rejected with a negative response.


Session Support

SNA Server supports three types of SNA communications sessions:

  • SSCP-PU

    The SNA Server PU Services Manager communicating with a host systems services control point (SSCP).

  • SSCP-LU

    An SNA Server LU communicating with a host SSCP.

  • PLU-SLU

    SNA Server LUs communicating with host or peer LUs.


Command Request Support

Tables 3.1 through 3.3 list the SNA command requests supported by SNA Server. Note that not all commands are supported for every LU-to-LU session type. For example, BIS is only supported for use by an APPC LU.

The tables list requests according to the following categories:

  • Session control requests
  • Function management data requests: network services (maintenance) and network services (session)
  • Data flow control requests

The category of each request is denoted by the setting of the request/response unit (RU) category bits in the request/response header (RH) and by the function of the request. SNA Server does not support commands that fall in the network control request category.

For more information about command requests, see your IBM documentation.

Table 3.1 SNA Request Support for Session Control Requests

Session | Request | Direction
SSCP-PU | ACTPU | SSCP to PU
 | DACTPU | SSCP to PU
SSCP-LU | ACTLU | SSCP to SLU
 | DACTLU | SLU to SSCP
PLU-SLU | BIND | PLU to SLU
 | UNBIND | PLU to/from SLU
 | CLEAR | PLU to SLU
 | SDT | PLU to SLU

Table 3.2 SNA Request Support for Function Management Data Requests

Session | Request | Direction
SSCP-PU | NMVT1 | SSCP to/from PU
 | INIT-SELF2 | SLU to SSCP
 | TERM-SELF2 | SLU to SSCP
 | NOTIFY2 | SLU to SSCP
 | NSPE2 | SSCP to SLU
1 Network services, maintenance services 2 Network services, session services

Table 3.3 SNA Request Support for Data Flow Control Requests

Session | Request | Direction
PLU-SLU | BID | PLU to/from SLU
 | BIS | PLU to/from SLU
 | CANCEL | PLU to/from SLU
 | CHASE | PLU to SLU
 | LUSTAT | PLU to/from SLU
 | RTR | PLU to/from SLU
 | SHUTC | PLU from SLU
 | SHUTD | PLU to SLU
 | SIGNAL | PLU to/from SLU


Transmission Service and Function Management Profiles

Transmission Service and
Function Management Profiles

SNA Server enforces the rules that govern active sessions between communicating partners on an SNA network.

The computer running SNA Server can select some of these session protocols — such as request/response control modes, bracket usage, and pacing — when you activate a session. Specific combinations of these selectable protocol options are called profiles.

TS profiles refer to transmission control options, while FM profiles refer to data flow control and function management data options.

When a session is activated, its TS and FM profiles are specified by using parameters in the appropriate session activation request and response (ACTPU, ACTLU, BIND).

Table 3.4 specifies the TS and FM profiles supported by each of the SNA Server session types.

Table 3.4 TS and FM Profiles Supported in SNA Server Sessions

Session type | TS Profiles | FM Profiles
SSCP-LU session | 1 | 0
SSCP-PU session | 1 | 0
3270 display and printer PLU-SLU session | 3 | 3
LU 6.2 PLU-SLU session | 7 | 19
LUA PLU-SLU session | 2, 3, 4 | 2, 3, 4, 7, 18

The following sections describe the TS and FM profiles that SNA Server supports.


TS Profile 1

TS Profile 1 is supported on SSCP-PU (physical unit) and SSCP-SLU sessions; the profile does not require the use of a TS Usage field. This profile specifies the following session rules:

  • No pacing.
  • Identifiers rather than sequence numbers are used on the normal flows.
  • ACTPU, DACTPU, ACTLU, and DACTLU are supported.
  • Maximum outbound RU size of 256 bytes.
  • Maximum inbound RU size of 512 bytes.


TS Profile 2

TS Profile 2 is supported on PLU-SLU sessions using LU type 0. This profile specifies the following session rules:

  • PLU-SLU and SLU-PLU normal flows are paced.
  • Sequence numbers are used on the normal flows (whenever the transmission header (TH) format used includes a sequence number field).
  • CLEAR is supported.
  • SDT, RQR, STSN, and CRV are not supported.

The TS Usage subfields defining the options for this profile are as follows:

  • Pacing window counts.
  • Maximum RU sizes on the normal flows.


TS Profile 3

TS Profile 3 is supported on PLU-SLU sessions using LU type 0, 1, 2, or 3. Selection is a BIND option. This profile specifies the following session rules:

  • PLU-SLU and SLU-PLU normal flows are paced.
  • Sequence numbers are used on the normal flows.
  • BIND, UNBIND, CLEAR and SDT are supported.

The TS Usage subfields defining the options for this profile are as follows:

  • Pacing counts.
  • Maximum RU sizes on the normal flows.


TS Profile 4

TS Profile 4 is supported on LU-LU sessions using LU type 0 or 1. This profile specifies the following session rules:

  • PLU-SLU and SLU-PLU normal flows are paced.
  • Sequence numbers are used on the normal flows (whenever the TH format used includes a sequence number field).
  • SDT, CLEAR, RQR, and STSN are supported.
  • CRV is supported when session-level cryptography is selected (via a BIND parameter).

The TS Usage subfields defining the options for this profile are as follows:

  • Pacing window counts.
  • Maximum RU sizes on the normal flows.


TS Profile 7

TS Profile 7 is supported on PLU-SLU sessions using LU type 6.2. This profile specifies the following session rules:

  • PLU-SLU and SLU-PLU normal flows are paced.
  • Sequence numbers are used on the normal flows.
  • BIND and UNBIND are supported.

The TS Usage subfields defining the options for this profile are as follows:

  • Pacing counts.
  • Maximum RU sizes on the normal flows.


FM Profile 0

FM Profile 0 is supported on SSCP-PU and SSCP-SLU sessions. This profile specifies the following session rules:

  • SSCP, PU, and SLU use immediate request mode and immediate response mode.
  • Only single-RU chains are allowed.
  • All chains require definite response.
  • No compression.
  • No data flow control (DFC) RUs.
  • No FM headers.
  • No brackets.
  • No alternate code.
  • Normal flow send/receive mode is half-duplex contention.
  • Secondary wins contention.
  • SSCP is responsible for recovery.


FM Profile 2

FM Profile 2 is supported on PLU-SLU sessions using LU type 0. This profile uses the following session rules:

  • SLU uses delayed request mode.
  • SLU uses immediate response mode.
  • Only single-RU chains are allowed.
  • SLU requests indicate no-response.
  • No FMH-1 SCB Compression.
  • Length-checked compression allowed.
  • No DFC RUs.
  • No FM headers.
  • SLU is first speaker if brackets are used.
  • Bracket termination rule 2 is used if brackets are used.
  • PLU will send End Bracket (EB).
  • SLU will not send EB.
  • Normal-flow send/receive mode is FDX.
  • PLU is responsible for recovery.

The following FM Usage fields define the options for Profile 2:

  • Primary request control mode selection.
  • Primary chain response protocol (no-response cannot be used).
  • Brackets usage and reset state.
  • Alternate code.


FM Profile 3

FM Profile 3 is supported on PLU-SLU sessions using LU type 0, 1, 2, or 3. This profile specifies the following session rules:

  • PLU and SLU use immediate response mode.
  • PLU and SLU support the following DFC commands (an asterisk [*] indicates commands permitted by the FM profile that are never sent by SNA Server):
    • CANCEL
    • SIGNAL
    • LUSTAT (SLU-PLU only)
    • CHASE*
    • SHUTD
    • SHUTC
    • RSHUTD*
    • BID and RTR

The following FM Usage fields define the options for Profile 3:

  • Chaining use (PLU and SLU).
  • Request control mode selection (PLU and SLU).
  • Chain response protocol (PLU and SLU).
  • Compression indicator (PLU and SLU).
  • Send EB indicator (PLU and SLU).
  • FM header usage.
  • Bracket usage.
  • Bracket termination rule.
  • Alternate Code Set Allowed indicator.
  • Normal-flow send/receive mode.

Tables 3.5 through 3.7 list the FM Profile 3 options that SNA Server supports. SNA Server rejects any bind that specifies an option value not listed in these tables.

Table 3.5 Supported Options for Bind Requests from Primary LUs

Usage Option | Value | Meaning
Chaining use element | 0 | Can send only single-element chains
 | 1 | Can send single- or multiple-chains
Request control mode | 0 | Immediate request mode used
Chain response protocol | 01 | Can request only exception-only responses
 | 10 | Can request only definite responses
 | 11 | Can request definite or exception-only responses
Compression indicator | 0 | Cannot send compressed data
 | 1 | Can send compressed data (LU type 1 only)
Send EB indicator | 1 | Can send End Bracket

Table 3.6 Supported Options for Bind Requests from Secondary LUs

Usage Option | Value | Meaning
Chaining use element | 0 | Can only send single-element chains (not LU type 2)
 | 1 | Can send single- or multiple-chains
Request control mode | 0 | Immediate request mode used
Chain response protocol | 01 | Can request only exception-only responses
 | 10 | Can request only definite responses
 | 11 | Can request definite or exception-only responses
Compression indicator | 0 | Cannot send compressed data
Send EB indicator | 1 | Cannot send End Bracket

Table 3.7 Supported Common Protocol Values for Bind Requests from Any LU

Usage Option | Value | Meaning
FM header usage | 0 | Cannot exchange FM headers
 | 1 | Can exchange FM headers
Bracket usage | 1 | Bracket protocols must be used
Bracket termination rule | 1 | Bracket termination rule 1 is used
Alternate code set allowed | 0 | Must use EBCDIC
Normal flow send/receive mode | 10 | Half-duplex flip-flop


FM Profile 4

FM Profile 4 is supported on PLU-SLU sessions using LU type 0 or 1. This profile uses the following session rules:

  • PLU and SLU use immediate response mode.
  • PLU and SLU support the following DFC commands (an asterisk [*] indicates commands permitted by the FM profile that are never sent by SNA Server):
    • CANCEL
    • SIGNAL
    • LUSTAT
    • QEC
    • QC
    • RELQ
    • CHASE*
    • SHUTD
    • SHUTC
    • RSHUTD*
    • BID and RTR (allowed only if brackets are used)
  • Length-checked compression allowed.

The following FM Usage fields define the options for Profile 4:

  • Chaining use (PLU and SLU).
  • Request control mode selection (PLU and SLU).
  • Chain response protocol (PLU and SLU).
  • FMH-1 SCB Compression indicator (PLU and SLU).
  • Send EB indicator (PLU and SLU).
  • FM header usage.
  • Brackets usage and reset state.
  • Bracket termination rule.
  • Alternate Code Set Allowed indicator.
  • Normal-flow send/receive mode.
  • Recovery responsibility.
  • Contention winner/loser.
  • Half-duplex flip-flop reset states.


FM Profile 7

FM Profile 7 is supported on PLU-SLU sessions using LU type 0. This profile uses the following session rules:

  • PLU and SLU use immediate response mode.
  • PLU and SLU support the following DFC commands (an asterisk [*] indicates commands permitted by the FM profile that are never sent by SNA Server):
    • CANCEL
    • SIGNAL
    • LUSTAT
    • RSHUTD*
  • Length-checked compression is allowed on LU 0 only.

The following FM Usage fields define the options for Profile 7:

  • Chaining use (PLU and SLU).
  • Request control mode selection (PLU and SLU).
  • Chain response protocol (PLU and SLU).
  • FMH-1 SCB Compression indicator (PLU and SLU).
  • Send EB indicator (PLU and SLU).
  • FM header usage.
  • Brackets usage and reset state.
  • Bracket termination rule.
  • Alternate Code Set Allowed indicator.
  • Normal-flow send/receive mode.
  • Recovery responsibility.
  • Contention winner/loser.
  • Half-duplex flip-flop reset states.


FM Profile 18

FM Profile 18 is supported on PLU-SLU sessions using LU type 0. This profile uses the following session rules:

  • PLU and SLU use immediate response mode.
  • PLU and SLU support the following DFC commands (an asterisk [*] indicates commands permitted by the FM profile that are never sent by SNA Server):
    • CANCEL
    • SIGNAL
    • LUSTAT
    • BIS and SBI (allowed only if brackets are used)
    • CHASE*
    • BID and RTR (allowed only if brackets are used)
  • Length-checked compression allowed.

The following FM Usage fields define the options for Profile 18:

  • Chaining use (PLU and SLU).
  • Request control mode selection (PLU and SLU).
  • Chain response protocol (PLU and SLU).
  • FMH-1 SCB Compression indicator (PLU and SLU).
  • Send EB indicator (PLU and SLU).
  • FM header usage.
  • Brackets usage and reset state.
  • Bracket termination rule.
  • Alternate Code Set Allowed indicator.
  • Normal-flow send/receive mode.
  • Recovery responsibility.
  • Contention winner/loser.
  • Half-duplex flip-flop reset states.


FM Profile 19

FM Profile 19 is supported on PLU-SLU sessions using LU type 6.2. This profile specifies the following session rules:

  • PLU and SLU use immediate request mode.
  • PLU and SLU use immediate response mode.
  • Multiple RU chains are allowed.
  • PLU and SLU requests indicate definite or exception response.
  • No compression.
  • Brackets are used.
  • FM headers (types 5, 7, and 12 only) are allowed.
  • Conditional termination for brackets (specified by Conditional End Bracket [CEB]) is used.
  • PLU and SLU may send CEB.
  • Normal-flow send/receive mode is half-duplex flip-flop.
  • Half-duplex flip-flop reset state is SEND for PLU.
  • Symmetric error responsibility.
  • Contention winner/loser negotiated at BIND time.
  • PLU and SLU support the following DFC commands:
    • SIGNAL
    • LUSTAT
    • BIS
    • RTR
  • The following combinations of RQE, RQD, CEB, and CD are allowed on end-chain RUs:

    RQE CD CEB

    RQD2 CD CEB

    RQD3 CD CEB

    RQE1 CD CEB

    RQD CD CEB

    The only option for Profile 19 is contention winner/loser.


Option Set Support

Table 3.8 lists the option sets supported by SNA Server. The reference numbers are those specified in IBM documentation.

Table 3.8 SNA Server Option Set Support

Ref No. | Option Set
101 | Flush the send buffer of the LU
102 | Get attributes
103 | Post on receipt with test for posting (supported by asynchronous APPC verbs)
104 | Post on receipt with wait (supported by asynchronous APPC verbs)
105 | Prepare to receive
106 | Receive immediate
109 | Get TP name and instance identifier
110 | Get conversation type
201 | Queued allocation of a contention winner session
203 | Immediate allocation of a session
204 | Conversations between programs located at the same LU
205 | Queued allocation for when session free
211 | Session-level LU-LU verification
212 | User ID verification
213 | Program-supplied user ID and password
214 | User ID authorization
241 | Send program initialization parameter (PIP) data
243 | Accounting
244 | Long locks
245 | Test for request-to-send received
246 | Data mapping
251 | Extract transaction and conversation identification information
290 | Logging of data in a system log
291 | Mapped conversation LU services component
505 | LU definition verbs (operator only)
601 | MIN_CONWINNERS_TARGET parameter
602 | RESPONSIBLE(TARGET) parameter
603 | DRAIN_TARGET(NO) parameter
605 | LU-LU session limit
606 | Locally known LU names
607 | Uninterpreted LU names
610 | Maximum RU size bounds
612 | Automatic activation limit for contention winner


SNA Sense Codes

If there is a communication problem during an SNA session, SNA Server can generate sense codes that notify the remote system of the type of problem. The sense codes fall into five distinct categories, corresponding to the type of problem that occurred:

Value | Category
X'08' | Request Reject
X'10' | Request Error
X'20' | State Error
X'40' | RH Usage Error
X'80' | Path Error

The following sections list the sense codes by category, and include two additional categories of sense codes:

  • Sense codes sent by a 3270 emulator on LUSTAT requests
  • Sense codes that can only flow on LU type 6.2 sessions


Request Reject (Category X'08')

This category indicates that the request was delivered to the intended half session, and was understood and supported, but not executed. The following codes are in this category:

Code | Meaning
0801 | Resource not available
0802 | Intervention required (LU1/LU3 printer soft error)
0805 | Session limit exceeded
0809 | Mode inconsistency
080A | Permission rejected, NOTIFY will not be sent
080B | Bracket race error
080C | Procedure not supported
0812 | Insufficient resources
0814 | Bracket bid reject-RTR forthcoming
0815 | Function active
081B | Contention race condition
081C | Request not executable (hard error)
0821 | Invalid session parameters
0829 | Change direction required
082B | Presentation space integrity lost
082D | LU busy (usually local copy print in progress)
082E | Intervention required (local copy print soft error)
082F | Request not executable (local copy print hard error)
0831 | LU component disconnected
0843 | WCC print command not sent (RQD or RQE, CD, EB)
0845 | Permission rejected, NOTIFY will be sent
0863 | Referenced character set does not exist
0871 | Read partition state error (SLU in retry state)


Request Errors (Category X'10')

Sense codes in this category represent an imbalance in half-session capabilities. They indicate that the RU was delivered to the intended half-session but could not be processed. The following codes are in this category:

Code | Meaning
1003 | Function not supported (also used instead of X'0826', which is not supported by SNA Server).
1005 | Parameter modifying a control function is invalid.
1007 | Category not supported (SSCP data for host printer).


State Errors (Category X'20')

Sense codes in this category indicate a sequence number error, or an RH or RU that is not allowed in the receiver's current state. This condition prevents delivery of the request to the intended half-session. The following codes are in this category:

Code | Meaning
2001 | Sequence number error
2002 | Chaining error
2003 | Bracket error
2004 | Direction error
2005 | Data traffic reset
2006 | Data traffic quiesced
2007 | Data traffic not quiesced


RH Usage Errors (Category X'40')

These sense codes indicate that fields in the RH are contrary to SNA rules or previously selected BIND options and prevent the intended half-session from receiving the request.

Also, the checks 400A and 4012 are performed. These do not permit negative responses, because they apply to no-response sessions and responses, respectively.

The following codes are in this category:

Code | Meaning
4006 | Exception response not allowed.
4007 | Definite response not allowed.
400F | Incorrect use of format indicator.
4011 | Incorrect specification of RU category.
4014 | Incorrect use of DR1, DR2, ER.


Path Errors (Category X'80')

Sense codes in this category indicate that the request could not be delivered to the required half-session because of path errors. The following codes are in this category:

Code | Meaning
8004 | Unrecognized destination field address (DAF).
8005 | No session.
8006 | Invalid FID: Error detected and logged; negative response not sent.
8007 | Segmentation error RH not present or too short: negative response sent only for segmentation error.
8008 | PU not active: SSCP-PU was not active and request was not ACTPU or DACTPU.
8009 | LU not active: DAF specified an LU for which the SSCP-SLU session has not been activated, and request was not ACTLU or DACTLU.
800F | Invalid address combination.


LUSTAT Sense Codes

The following sense codes are sent by a 3270 emulator on LUSTAT requests.

Code | Meaning
0001 B000 | Host initialized local copy soft error recovery.
081C 0000 | Soft error changed to hard error (LU1/LU3).
081C B000 | Soft error changed to hard error (local copy).
082B 0000 | SLU session changed from SSCP to PLU (SYSREQ).


Sense Data Specific to LU Type 6.2

The LU type 6.2 sense codes are specified and interpreted by SNA components within SNA Server, and, in general, are presented as return codes and as parameters to specific verbs.

The following sense codes are carried on responses flowing on LU type 6.2 sessions.

Code | Meaning
0814 | Bracket bid reject — RTR forthcoming.
0819 | RTR not required — receiver of RTR request has nothing to send.
0835 | Invalid parameter — request contained a fixed or variable field which is invalid. Bytes 2 and 3 contain a 2-byte binary count which indexes the field error (zero origin).
0846 | ERP message forthcoming: The received request was rejected for a reason to be specified in a forthcoming FMH-7 request — which itself carries SNA sense data (see the following table for a list of these codes).
088B | BB not accepted — BIS reply requested.
2010 | BIS protocol error —receiver detected a BIS error; for example, two BIS replies received.

The following data is carried on an FMH-7 request, flowing after the flow of a negative response X'0846'.

Code | Meaning
1008 600B | Resource failure no retry
1008 6021 | Allocation error TPN not recognized
1008 6031 | Allocation error PIP not allowed
1008 6032 | Allocation error PIP not specified correctly
1008 6034 | Allocation error conversation type mismatch
1008 6041 | Allocation error sync level not supported by pgm
080F 6051 | Allocation error security not valid
084B 6031 | Allocation error trans pgm not available retry
084C 0000 | Allocation error trans pgm not available no retry
0864 0000 | Deallocate abend prog
0864 0001 | Deallocate abend svc
0846 0002 | Deallocate abend timer
0889 0000 | Prog error no trunc or prog error purging
0889 0001 | Prog error trunc
0889 0100 | Svc error no trunc or svc error purging
0889 1001 | Svc error trunc


Chapter 4 Network Management

This chapter describes the support that SNA Server provides for centralized network management. The following topics are discussed:

  • Connections used for the NetView® and Response Time Monitor (RTM) facilities
  • Link alerts
  • Link statistics
  • Application-generated alerts, and alerts generated through the NVAlert and NVRunCmd services
  • RTM statistics
  • Local logging of network management data

For information about configuring SNA Server to work with NetView and/or RTM, and information about configuring the NVAlert and NVRunCmd services, see the Microsoft SNA Server Administration Guide.


Connections Used for NetView and RTM

SNA Server can make use of NetView, a reporting system that runs on an IBM host (mainframe). NetView sends alerts between the host and the PCs that connect to it. SNA Server can also receive information from RTM, a 3270 and NetView facility that monitors the amount of time it takes for a host to respond during 3270 display sessions.

To send link alerts, link statistics, and application-generated alerts to the NetView program at the host, you must specify the connection on which the alerts will be sent. See SNA Server Manager Help for information about specifying the connection.

RTM data and NetView alerts sent to the host by 3270 users are not necessarily sent via the NetView connection. RTM data is sent on the connection for the session to which it refers, while 3270 user alerts are sent on the connection for the currently selected 3270 session.

For information about configuring SNA Server Manager to work with NetView and/or RTM, and information about configuring the NVAlert and NVRunCmd services, see the Microsoft SNA Server Administration Guide.


Link Alerts for SDLC and Token Ring

When a Synchronous Data Link Control (SDLC) or token ring connection fails, SNA Server logs diagnostic information, called link alerts, about the connection failure. The alerts are logged in a log file that can be viewed using the Windows NT Event Viewer. To find an SNA Server log, in the Event Viewer, from the Log menu, make sure Application is selected. Under the "Source" heading, the application log file will have a name starting with "SNA."

The link alerts are also used to build a network management vector transport (NMVT) alert, which includes probable causes and suggested actions for the alert. If a connection on the server running SNA Server has been designated for NetView, and the connection is active, the NMVT alert will be sent on that connection.

This section contains the following information:

  • An explanation of the general format of link alerts, common to both SDLC and token ring.
  • Descriptions of individual alerts produced by the SDLC link service.
  • Detailed information about the local logging of SDLC alerts.
  • Descriptions of individual alerts produced by the token ring link service.
  • Details of the local logging of token ring alerts.

For information about the NetView vectors supported by the NVAlert and NVRunCmd services, see "Alerts Used by Applications, NVAlert, and NVRunCmd" later in this chapter.


Link Alert Format and Common Subvectors

The general format of link alerts is as follows:

NMVT HEADER
41 03 8D 00 00 00 00 00     NMVT Header

Major Vector Header
LL LL     Length of Major Vector
00 00     Alert major vector

The specific alert is identified by the alert description and alert ID (part of the generic alert subvector). Common subvectors are listed later in this section. SDLC and token ring failure alerts are described in the "SDLC Failure Alerts" and "Token Ring Failure Alerts" sections, respectively, later in this chapter.

Each subvector or subfield begins with a 1-byte length field and a 1-byte key identifying the subvector or subfield. The length field contains the length in bytes of the entire subvector or subfield, including the length and key bytes. Where the length byte is shown as LL, this indicates that the length is not fixed because different alerts require different data to be included.

Table 4.1 lists all the possible subvectors used in the alert, with their subvector keys (identifiers).

Table 4.1 Link Alert Subvectors

Subvector key (identifier) | Subvector
05 | Hierarchy/Resource List Subvector.
03 | Hierarchy Name List Subvector.
01 | Date/Time Subvector.
10 | Product Set ID Subvector (this appears twice, as Alert Sender PSID and Indicated Resource PSID).
51 | LAN LCS Data Subvector.
52 | LCS Configuration Data Subvector.
8C | Link Station Data Subvector.
91 | Basic Alert Subvector.
92 | Generic Alert Subvector.
93 | Probable Cause Subvector.
94 | User Causes Subvector.
95 | Install Causes Subvector.
96 | Failure Causes Subvector.
A1 | Detail Qualifier Subvector.

The following tables describe the formats of link alert subvectors. Additional tables, later in this chapter, describe the individual link alerts.

Hierarchy/Resource List Subvector

Format and contents | Description
LL 05 | Hierarchy/Resource List Subvector.
LL 10 | Hierarchy/Resource List Subfield.
hh | Flags: 80 (1-User) 00 (Server).
LL | Name field length: name length plus this length byte.
hh...hh | Adapter name in EBCDIC, 8 bytes.
00 | Flags byte: always 0.
3F | Resource type: port.
Optional second name | Remote host name. For token ring, local ring name. See individual alert descriptions.
LL | Name field length: name length plus this length byte.
hh...hh | Name in EBCDIC, up to 8 bytes.
00 | Flags byte: always 0.
F4 or 2E | Resource type: control point or token ring.

Hierarchy/Name List Subvector

Format and contents | Description
LL 03 | Hierarchy Name List subvector.
00 or 03 | Reserved byte.
hh | Number of names in the hierarchy name list.
LL | Length of each name, including this length byte.
hh...hh | Name of resource for each name.
D3 C3 D6 D5 | Resource type identifier: LCON (logical link connection not known to SNA).

Date/Time Subvector Alerts

Format and contents | Description
0A 01 | Date/Time Subvector.
08 10 | Local Date/Time subfield.
hh | Year — two digits.
hh | Month.
hh | Date.
hh | Hours.
hh | Minutes.
hh | Seconds (binary).

Product Set ID Subvector

Format and contents | Description
2A 10 | Product Set ID subvector.
00 | (unused field).
27 11 | Product ID subvector.
0C | Product classification: non-IBM software.
08 04 | Software product common level subfield.
F0 F2 | Version identifier: 02.
F0 F0 | Release identifier: 00.
F0 F0 | Modification identifier: 00.
13 06 | Software product common name subfield.
C4 C3 C1 61 D4 E2 40 C3 D6 D4 D4 40 E2 C5 D9 E5 D9 | Product name: MS® SNA Server
09 08 | Software product program number subfield.
F0 F0 F0 F0 F0 F0 F0 | Product program number: zeros.

LAN Link Connection Subsystem Data Subvector*

Format and contents | Description
LL 51 | LAN LCS Data Subvector.
04 02 | Ring Identifier subfield.
hh hh | Ring number.
08 03 | Local Individual MAC Address subfield.
hh...hh | Local individual MAC address.
08 04 | Remote Individual MAC Address subfield.
hh...hh | Remote individual MAC address.
LL 05 | LAN Routing Information subfield.
hh...hh | LAN routing information
* Token ring only.

Link Connection Subsystem Configuration Data Subvector

Format and contents | Description
LL 52 | LCS Configuration Data Subvector.
04 01 | Port Address subfield.
hh hh | Port address.
03 02 | Remote Device Address subfield.
hh | Remote device address.
03 04 | Local Device Address subfield.
hh | Local device address.
04 06 | Link Station Attributes subfield.
01 or 02 or 03 | Link station role: Primary, Secondary, or Negotiable.
03 or 04 | Remote node type: Type 4 or Type 2.1.
06 07 | Link Attributes subfield.
01 or 02 | Link connection type: nonswitched or switched.
01 or 02 | Half-duplex or full-duplex.
01 | Protocol: SDLC.
01 or 02 | Point-to-point or multipoint.

Link Station Data Subvector

Format and contents | Description
LL 8C | Link Station Data Subvector.
04 01 | N(s) and N(r) counts subfield.
hh | N(s) count.
hh | N(r) count.
03 02 | Outstanding frame count subfield.
hh | Outstanding frame count.
04 03 | Last SDLC Control Field Received subfield.
hh hh | Last control field received.
04 04 | Last SDLC Control Field Sent subfield.
hh hh | Last control field sent.
03 05 | Sequence Number Modulus subfield.
80 | Sequence number modulus.
03 06 | Link Station State subfield.
80 or 40 | Link station state: local or remote station sending RNR.
04 07 | LLC Reply Timer Expiration Count subfield.
hh hh | Reply timer expiration count.
03 08 | Last Received N(r) Count subfield.
hh | Last received N(r) (binary).

Basic Alert Subvector

Format and contents | Description
0E 91 | Basic Alert subvector.
00 | Not operator initiated.
01 | Alert type: permanent.
0E | General cause code: link-level protocol error.
00 80 or 00 34 | Specific component code: token ring LAN or SDLC data link control.
00 00 | Alert description code.
00 00 | User action code.
00 00 | Detail text reference code.
00 | Unused field.

Generic Alert Subvector

Format and contents | Description
0B 92 | Generic Alert subvector.
00 00 | Flags: not operator initiated, not a held alert.
01 | Alert type: permanent.
hh hh | Alert description: See alert descriptions.
hh hh hh hh | Alert ID number (unique to a particular alert).

Probable Cause Subvector

Format and contents | Description
LL 93 | Probable cause subvector.
hh hh | Probable cause: See individual alert descriptions. This alert may include more than one entry.

User Causes Subvector

Format and contents | Description
LL 94 | User Causes Subvector.
LL 01 | User causes subfield.
hh hh | User cause: See individual alert descriptions. More than one entry may appear here.
LL 81 | Recommended actions subfield.
hh hh | Recommended action: See individual alert descriptions. More than one entry may appear here.
03 83 | Product set ID index subfield.
99 | Product Set ID index.
LL 82 | Detailed data subfield. This subfield may appear more than once.
99 | Product Set ID code.
hh | Data ID: See individual alert descriptions.
00 | Data encoding: hexadecimal.
hh...hh | Detailed data: See individual alert descriptions.

Install Cause Subvector

Format and contents | Description
LL 95 | Install Causes Subvector.
LL 01 | Install causes subfield.
hh hh | Install cause: See individual alert descriptions. More than one entry may appear here.
LL 81 | Recommended actions subfield.
hh hh | Recommended action: See individual alert descriptions. More than one entry may appear here.
03 83 | Product set ID index subfield.
99 | Product Set ID index.
LL 82 | Detailed data subfield. This subfield may occur more than once.
99 | Product Set ID code.
hh | Data ID: See individual alert descriptions.
00 | Data encoding: hexadecimal.
hh...hh | Detailed data: See individual alert descriptions.

Failure Cause Subvector

Format and contents | Description
LL 96 | Failure Causes Subvector.
LL 01 | Failure causes subfield.
hh hh | Failure cause: See individual alert descriptions. More than one entry may appear here.
LL 81 | Recommended actions subfield.
hh hh | Recommended action: See individual alert descriptions. More than one entry may appear here.
03 83 | Product set ID index subfield.
99 | Product Set ID index.
LL 82 | Detailed data subfield. This subfield may occur more than once.
99 | Product Set ID code.
hh | Data ID: See individual alert descriptions.
00 | Data encoding: hexadecimal.
hh...hh | Detailed data: See individual alert descriptions.

Detail Qualifier (Hexadecimal) Subvector

Format and contents | Description
06 A1 | Detail Qualifier subvector.
hh hh hh hh | Detail Qualifier subfield — four bytes as follows: Token ring: adapter number Alert number Two-byte error code SDLC: link ID Station address, outage


SDLC Failure Alerts

The tables in this section describe the alerts generated by the SDLC link service provided with SNA Server. The alerts are listed in numerical order by alert description and within each description in numerical order by alert ID.

Write Timeout Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 1000 | Equipment malfunction
Alert ID: | 61D0 2E7B |
Probable causes: | 2031 | Line
 | 3601 | Local modem
 | 2200 | Remote node
 | 3603 | Remote modem
Failure causes: | 3511 | Line
 | 3601 | Local modem
 | 2200 | Remote node
 | 3603 | Remote modem
 | F034 | CTS failed to rise
Recommended actions: | 0403 | Run modem tests
 | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 2E | Write timeout retry exceeded

Abnormal Modem Response Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 1000 | Equipment malfunction
Alert ID: | 70A1 5CB0 |
Probable causes: | 3601 | Local modem
 | 3401 | Local cable
 | 3302 | Communications adapter
User causes: | 3401 | Cabling installed incorrectly
Recommended actions: | 0301 | Check cable and its connections
Failure causes: | 3601 | Local modem
 | 3401 | Local cable
 | 3302 | Communications adapter
 | F035 | DSR dropped
Recommended actions: | 0403 | Run modem tests
 | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 2D | Abnormal response

DSR Failure Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 1000 | Equipment malfunction
Alert ID: | 83BB 6EC8 |
Probable causes: | 3601 | Local modem
 | 3401 | Local cable
 | 3302 | Communications adapter
User causes: | 3400 | Cable loose
 | 0205 | Local modem power off
Failure causes: | 3601 | Local modem
 | 3401 | Local cable
 | 3302 | Communications adapter
 | F035 | DSR dropped
Recommended actions: | 0403 | Run modem tests
 | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 11 | DSR failure

DCD Failure Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 1000 | Equipment malfunction
Alert ID: | C3BB 504A |
Probable causes: | 2031 | Line
 | 3601 | Local modem
Failure causes: | 3511 | Line
 | 3601 | Local modem
 | F038 | Carrier detect lost
Recommended actions: | 0403 | Run modem tests
 | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 14 | DCD failure

Invalid Frame Received: I-Field Not Permitted Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 1103 D152 |
Probable causes: | 2004 | SDLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F021 | I-field received when not permitted
Recommended actions: | 2011 | Review hexadecimal display of alert report
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 87 | Invalid frame received

Invalid Frame Received: Invalid/Unsupported CMD/RSP Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 15C2 CCE5 |
Probable causes: | 2004 | SDLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F020 | Invalid/unsupported command or response received
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 87 | Invalid frame received

Invalid Frame Received: Invalid N(R) Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 1C40F78B |
Probable causes: | 2004 | SDLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F022 | Invalid N(R) received
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 87 | Invalid frame received

RIM/RD Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 29BF 0032 |
Probable causes: | 2104 | SDLC communications/remote node
 | 1023 | Communications program in remote node
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 88 | RIM received
 | 89 | RD received

Invalid Frame Received: Max I-Field Length Exceeded Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 5F76 24FD |
Probable causes: | 2104 | SDLC communications/remote node
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F023 | Received I-field exceeded maximum length
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 87 | Invalid frame received

FRMR Received: No Reason Given Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | A472 BC48 |
Probable causes: | 2004 | SDLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F014 | FRMR received: no reason specified
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 86 | FRMR received

FRMR Received: I-Field Received When Not Permitted

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | B3B7 D723 |
Probable causes: | 2004 | SDLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F011 | FRMR received: I-field sent when not permitted
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 86 | FRMR received

FRMR Received: Invalid/Unsupported Command or Response Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | B776 CA94 |
Probable causes: | 2004 | SDLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F010 | FRMR received: invalid/unsupported command or response sent
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 86 | FRMR received

FRMR Received: Max I-Field Length Exceeded Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | BA35 EC4D |
Probable causes: | 2004 | SDLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F013 | FRMR received: maximum I-field length exceeded
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 86 | FRMR received

FRMR Received: Invalid N(R) Sent Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | BEF4 F1FA |
Probable causes: | 2004 | SDLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F012 | FRMR received: invalid N(R) sent
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 86 | FRMR received

DISK/SNRM Received: SNRM Received in NRM Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | D635 CA1E |
Probable causes: | 2004 | SDLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F015 | SNRM received while in NRM
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 15 | Connection terminated by host

CTS Failure Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | 0231 CF0A |
Probable causes: | 2031 | Line
 | 3601 | Local modem
Failure causes: | 3511 | Line
 | 3601 | Local modem
 | F030 | CTS dropped
Recommended actions: | 0403 | Run modem tests
 | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 12 | CTS failure

Connection Problem: XID Retransmission Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | 0AEC C2A6 |
Probable causes: | 2104 | SDLC communications/remote node
 | 2031 | Line
User causes: | 0209 | Remote device power off
Recommended action: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F018 | XID poll count exhausted

Idle Timeout Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | 0E2D DF11 |
Probable causes: | 2104 | SDLC communications/remote node
 | 2031 | Line
User causes: | 0209 | Remote device power off
Recommended action: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F019 | Inactivity timer expired
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 25 | Idle timeout retry exceeded

Poll Count Exhausted Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | 32A3 7F1B |
Probable causes: | 2104 | SDLC communications/remote node
 | 2031 | Line
User causes: | 0209 | Remote device power off
Recommended action: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F017 | Poll count exhausted
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 81 | Disconnect retry limit
 | 82 | Contact retry limit
 | 83 | Poll retry limit
 | 84 | No response retry limit

Remote Busy Retry Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | 66D6 DA74 |
Probable causes: | 2104 | SDLC communications/remote node
User causes: | 0209 | Remote device power off
Recommended actions: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F00F | RNR received threshold reached
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 85 | Remote busy retry limit

DM Received in Information Transfer Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | BD84 C4C9 |
Probable causes: | 2004 | SDLC communications
Failure causes: | 2004 | SDLC communications
 | F01A | DM received
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 80 | DM received

Nonproductive Receive Timeout Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | C458 E284 |
Probable causes: | 2104 | SDLC communications/remote node
 | 2031 | Line
User causes: | 0209 | Remote device power off
Recommended action: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F00E | NPR timeout retry limit reached
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 24 | Nonproductive receive retry exceeded

DISK/SNRM Received: Disk Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | D9C4 172B |
Probable causes: | 2004 | SDLC communications
Failure causes: | 2004 | SDLC communications
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 15 | Connection terminated by host

Connection Problem: I-Frame Retransmission Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3300 | Link error
Alert ID: | E3DA E42F |
Probable causes: | 2104 | SDLC communications/remote node
 | 2031 | Line
User causes: | 0209 | Remote device power off
Recommended action: | 0200 | Check power
Failure causes: | 2104 | SDLC communications/remote node
 | 3511 | Line
 | F06A | Transmit retry limit reached
Recommended actions: | 2011 | Review hexadecimal display of alert
 | 32A0 | Report the following detail qualifier: Outage qualifier
Detail qualifier: | 29 | Connection problem


SDLC Alert Local Logging

Before SNA Server attempts to build and send an SDLC Link Alert, information about the outage that caused the alert is logged in a log file that can be viewed using the Windows NT Event Viewer. Message 182 will always be logged, as follows:

182I:  Connection failure, code = (outagecode)
Cause Data                          = hh...hh
Link Role                           = hh
Remote Node Type                    = hh

The Outage Code (outagecode) is also reported on a 23 message. For a complete list of these codes, the conditions they represent, and the specific Link Alerts on which they are used, see the next section.

Cause Data is a list of the failure causes from the Failure causes subvector in the alert. Link Role and Remote Node type are as described in the Link Connection Subsystem Configuration Data subvector in the alert.

A connection failure can be due to a station outage, rather than a link outage. If it is due to a station outage — which can be recognized by outage code values of X'80' or higher — then message 183, formatted as follows, will also be logged:

183I:
Detailed diagnostic data for station (stationaddress):
SBSY   CFTX   CFRX   V(S)   V(R)   N(R)   OSFC   T1CT
hh     hhhh   hhhh   hh     hh     hh     hh     hhhh

The value (stationaddress) is the station address as given in the Detail qualifier subvector in the alert.

The other fields are all data from the Link Station Data subvector, as follows:

Field | Description
SBSY | Link station state: 80 or 40
 | (local or remote station sending RNR)
CFTX | Last SDLC control field sent
CRX | Last SDLC control field received
V(S) | N(S) count
V(R) | N(R) count
N(R) | Last received N(R)
OSFC | Outstanding frame count
T1CT | Reply timer expiration count

Identifying Alerts from Local Logs Only

When only the local log of an alert is available, you can still obtain the information that would have been supplied on the alert. To do this, check the outage code given on the 182 message against the following list to find the alert that uses this outage code, and then check the alert data in "SDLC Failure Alerts" earlier in this chapter. Some Outage Codes are used for more than one alert; in these cases, you can find the appropriate alert by comparing the failure causes codes given on the 182 message with those given in the alert data.

SDLC Outage Codes

Outage code | Condition | Alert description/ID
11 | DSR failure | 1000 : 83BB6EC8
12 | CTS failure | 3300 : 0231CF0A
14 | DCD failure | 1000 : C3BB504A
15 | Connection terminated by host | 2100 : D635CA1 :
24 | Nonproductive receive retry exceeded | 3300 : C458E284
25 | Idle timeout retry exceeded | 3300 : 0E2DDF11
29 | Connection problem | 3300 : 0AECC2
2D | Abnormal response | 1000 : 70A15CB0
2E | Write timeout retry exceeded | 1000 : 61D02E7B
80 | DM received | 3300 : BD84C4C9
81 | Disconnect retry limit | 3300 : 32A37F1B
82 | Contact retry limit | 3300 : 32A37F1B
83 | Poll retry limit | 3300 : 32A37F1B
84 | No response retry limit | 3300 : 32A37F1B
85 | Remote busy retry limit | 3300 : 66D6DA74
86 | FRMR received | 2100 : A472BC48
 |  | 2100 : B3B7D723
 |  | 2100 : B776CA94
 |  | 2100 : BA35EC4D
 |  | 2100 : BEF4F1FA
87 | Invalid frame received | 2100 : 1103D152
 |  | 2100 : 15C2CCE5
 |  | 2100 : 1C40F78B
 |  | 2100 : 5F7624FD
88, 89 | RIM or RD received | 2100 : 29BF0032


Token Ring Failure Alerts

The tables in this section describe the alerts generated by the token ring link service provided with SNA Server. The alerts are listed in numerical order by alert description and within each description in numerical order by alert ID.

Adapter Check Error: Adapter Error Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 1010 | Adapter error
Alert ID: | 3BA0 3B6D |
Probable causes: | 3320 | Local token ring adapter
Failure causes: | 3320 | Local token ring adapter
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following detail qualifier:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed Data: | 02 | Data ID: adapter check status
 | hh hh | Adapter check status
LAN LCS: |  | Ring identifier Local individual MAC address

DLC Status Error: FRMR Sent-Invalid N(R) Received

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 216D 1033 |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F012 | Invalid N(r) received
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Sent-Received I-Field Exceeded Maximum Length Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 25AC 0D84 |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F023 | Received I-field exceeded maximum length
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Sent-Invalid/Unsupported

Command/Response Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 28EF 2B5D |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F020 | Invalid/unsupported command or response received
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Sent-I-Field Received When Not Permitted Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 2C2E 36EA |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F021 | I-field received when not permitted
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

Adapter Command Error: Software Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | 3EF7 89B7 |
Probable causes: | 1000 | Software program
Failure causes: | 1000 | Software program
Recommended actions: | 30E1 | Contact service representative
 | 32C0 | Report the following data:
 |  | Product Set ID index subfield included
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 03 | Data ID: adapter return code
 | hh | Adapter return code

DLC Status Error: DM or Disk Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 4B74 26FB |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F01A | DM received
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Received-Invalid N(R) Sent Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 83D9 1642 |
Probable causes: | 2007 | LAN LLC communications
 | 1000 | Software program
Failure causes: | 1000 F012 | Software program Frame reject received: Invalid N(r) sent
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Received-Max I-Field Length

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 8718 0BF5 |
Probable causes: | 2007 | LAN LLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F013 | Frame reject received: maximum I-field length exceeded
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Received-Invalid/Unsupported Commands/Response Sent Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 8A5B 2D2C |
Probable causes: | 2007 | LAN LLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F010 | Frame reject received: Invalid/unsupported command or response sent
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: FRMR Received-I-Field Sent When Not Permitted Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | 8E9A 309B |
Probable causes: | 2007 | LAN LLC communications
 | 1000 | Software program
Failure causes: | 1000 | Software program
 | F011 | Frame reject received: I-field sent when not permitted
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

Software Program Error: Adapter Interface Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 2100 | Software program error
Alert ID: | DA7B C09D |
Probable causes: | 3220 | Token ring adapter interface
Install causes: | 1600 | Mismatch between software and microcode
 | 1601 | Incorrect customization image
Recommended actions: | 1500 | Correct installation problem
 | 1502 | Correct customization parameters
Failure causes: | 3220 | Token ring adapter interface
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Ring identifier Local individual MAC address

DLC Status Error: SABME Received for Open Link Station Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 2100 | Software program error
Alert ID: | E65B 0B7F |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
Failure causes: | 1023 | Communications program in remote node
 | F016 | SABME received while in ABME
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

Bring-Up Error Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3210 | Initialization failure
Alert ID: | AB86 8B0B |
Probable causes: | 3320 | Local token ring adapter
Install causes: | 1200 | Incorrect hardware configuration
 | 1402 | Mismatch between hardware and software configurations
Recommended actions: | 1503 | Correct configuration
Failure causes: | 3320 | Local token ring adapter
Recommended actions: | 30E1 | Contact service representative
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Local individual MAC address

Adapter Open Error: Open Failure Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is ring name
Alert description: | 3211 | Open failure
Alert ID: | 016E 5F4E |
Probable causes: | 3702 | Token ring lobe
 | 3701 | Token ring LAN component
Failure causes: | 3712 | Local token ring lobe
 | 3701 | Token ring LAN component
 | 2600 | Interference
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Local individual MAC address

Adapter Open Error: Remove Command Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3211 | Open failure
Alert ID: | 44D1 AD86 |
Probable causes: | 3705 | Token ring remove command received
User causes: | 3320 | Token ring remove adapter command received
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Local individual MAC address

Adapter Open Error: Problem on Local Lobe Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3211 | Open failure
Alert ID: | 55BF 3E1C |
Probable causes: | 3702 | Token ring lobe
Failure causes: | 3320 | Local token ring adapter
 | 3711 | Local token ring lobe
 | 3434 | Local lobe cables
Recommended actions: | 1009 | Try reopening adapter after 30 seconds
 | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Local individual MAC address

Adapter Open Error: Beaconing Detected Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3211 | Open failure
Alert ID: | CAF3 C58A |
Hierarchy/resource list: |  | Second name is ring name
Probable causes: | 3703 | Token ring fault domain
Failure causes: | 3703 | Token ring fault domain
Recommended actions: | 1009 | Try reopening adapter after 30 seconds
 | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code

Adapter Open Error: Duplicate Address Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3211 | Open failure
Alert ID: | D615 A61E |
Probable causes: | 3704 | Token ring duplicate station address
Install causes: | 3704 | Token ring duplicate station address assigned
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Local individual MAC address

System Action: Operator Caused LAN Adapter to Be Reset Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3211 | Open failure
Alert ID: | F7A6 2F59 |
Probable causes: | 7001 | Resources not active
User causes: | 3300 | Adapter not ready
Recommended actions: | 1300 | Correct then retry
 | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier local individual MAC address

Network Status Error: Lobe Wire Fault Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is ring name
Alert description: | 3212 | Wire fault
Alert ID: | A676 B230 |
Probable causes: | 3702 | Token ring lobe
Failure causes: | 3711 | Local access unit
 | 3434 | Local lobe cables
 | 3320 | Local token ring adapter
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 17 | Data ID: ring status code
 | hh hh | Ring status code
LAN LCS: |  | Local individual MAC address

Network Status Error: Auto-Removal Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is ring name
Alert description: | 3213 | Auto-removal
Alert ID: | EB61 E14F |
Probable causes: | 3702 | Token ring lobe
Failure causes: | 3320 | Local token ring adapter
 | 3711 | Local access unit
 | 3434 | Local lobe cables
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 17 | Data ID: ring status code
 | hh hh | Ring status code
LAN LCS: |  | Local individual MAC address
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 17 | Data ID: ring status code
 | hh hh | Ring status code
LAN LCS: |  | Local individual MAC address

Network Status Error: Token Ring Remove Adapter Command Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 3214 | Remove adapter command received
Alert ID: | 59F3 2622 |
Probable causes: | 7013 | LAN Manager operator
User causes: | 7101 | Token ring remove adapter command received
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 17 | Data ID: ring status code
 | hh hh | Ring status code
LAN LCS: |  | Ring identifier Local individual MAC address

Network Status Error: LLC Remove Adapter Command Received Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 3300 | Link error
Alert ID: | 5B8F 5BA7 |
Probable causes: | 2017 | LAN LLC communications/remote node
Failure causes: | 2107 | LAN LLC communications/remote node
 | F017 | Poll count exhausted
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address
Link Station Data subvector included |  |

DLC Status Error: Link Lost Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 3300 | Link error
Alert ID: | 9921 0A2B |
Probable causes: | 3321 | Remote token ring adapter
Failure causes: | 3321 | Remote token ring adapter
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address

DLC Error: Remote Station Not On Local or Attached Rings Alert

Name of subvector | Hexadecimal value in subvector | Description
Hierarchy/resource list: |  | Second name is remote node CP name
Alert description: | 3305 | Unable to communicate with remote node
Alert ID: | D91B 9E2D |
Probable causes: | 2007 | LAN LLC communications
 | 1023 | Communications program in remote node
User causes: | 0209 | Remote device power off
Recommended actions: | 0200 | Check power
Failure causes: | 1023 | Communications program in remote node
Recommended actions: | 3301 | If problem persists do the following:
 | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32A0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address Remote individual MAC address LAN routing information
LCS configuration: |  | Remote device address Local device address

Adapter Command Error: Storage Capacity Exceeded Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 5003 | Capacity exceeded
Alert ID: | 9C35 13D5 |
Probable causes: | 0101 | Main storage
Failure causes: | 0110 | Storage control
Recommended actions: | 2010 | Review link detailed data
 | 3103 | Contact LAN administrator responsible for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 03 | Data ID: adapter return code
 | hh | Adapter return code
LAN LCS: |  | Ring identifier Local individual MAC address

Adapter Check Error: Receive Queue Overrun Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 5012 | Receive queue overrun
Alert ID: | 14D5 3710 |
Probable causes: | 1000 | Software program
Failure causes: | 1000 | Software program
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32A0 | Report the following data:
 |  | Product Set ID index subfield included
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
LAN LCS: |  | Ring identifier Local individual MAC address

Adapter Check Error: Microcode Program Abnormally Terminated Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 6000 | Microcode program abnormally terminated
Alert ID: | E1EC 74A7 |
Probable causes: | 3320 | Local token ring adapter
Failure causes: | 3320 | Local token ring adapter
Recommended actions: | 2010 | Review link detailed data
 | 3101 | Contact token ring administrator for this LAN
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 07 | Data ID: error code
 | hh hh | Error code
LAN LCS: |  | Ring identifier Local individual MAC address

Adapter Command Error: Configuration Alert

Name of subvector | Hexadecimal value in subvector | Description
Alert description: | 8000 | Configuration error
Alert ID: | B8AB EF98 |
Probable causes: | 7001 | Local system operator
Install causes: | 1501 | Incorrect customization parameters
 | 1400 | Mismatch between hardware and software
Recommended actions: | 3110 | Contact communications systems programmer
 | 32C0 | Report the following data:
Detailed data: | 61 | Data ID: adapter number
 | hh | Adapter number
Detailed data: | 03 | Data ID: adapter return code
 | hh | Adapter return code


Link Statistics

For SDLC and token ring connections, SNA Server maintains statistics on link usage and errors. This information is logged when a connection ends or when the counter for a particular error or time-out reaches its maximum value.


Format for Link Statistics

When an SDLC or token ring connection ends, or when an error counter reaches its maximum value, statistics on link usage are recorded. These statistics include information such as the adapter number, the date and time the link was established, and counts of errors and time-outs. This data is also logged in NMVT format if a connection has been specified for carrying NetView data, and is then sent if that connection and the server that owns that connection are both active.

SDLC Link Statistics

Link statistics are generated when a link is closed or when one of the wrap counters listed later in this section is about to wrap. Whenever a link statistics message is built, all the wrap counters are reset to 0. The cumulative counters are not reset, and provide statistics from the point at which the particular link service was started.

The NMVT generated has the following format:

NMVT Header

41 03 8D 00 00 00 00 00

NMVT Header

Major Vector Header
00 69 | Length of major vector
00 25 | Link Statistics major vector

Data Link Traffic Counters Subvector
65 9A | Data Link Traffic Counters subvector
03 | DLC type: SDLC
hh | Adapter number (01+04)

Date/Time Link Established
hh | Date
hh | Month
hh hh | Year
hh | Hour
hh | Minute
hh | Second
hh | Hundredths of a second
hh | Counter

Wrap Counters
hh | Transmit I-frames OK
hh | Transmit I-frames not OK
hh | Retransmit I-frames
hh | Received I-FCS OK
hh | Received I-FCS not OK
hh | Total frames sent
00 | Reserved
hh | Lost data frames received
hh | FRMR conditions sent
00 | Reserved
hh | CTS drop
00 | Reserved
00 | Reserved
hh | DSR drop out
hh | Inactivity timeouts
00 | Reserved
hh | DMA underruns
00 | Reserved
hh | Transmit fail timeouts
00 | Reserved

Cumulative Counters

The cumulative counters are the same counters as the wrap counters, with reserved bytes in the same positions.


Token Ring Link Statistics

Link statistics are generated when a link is closed or when one of the following counters is about to wrap. Whenever a link statistics message is built, all the counters are reset to 0.

The NMVT generated has the following format:

NMVT Header

41 03 8D 00 00 00 00 00

NMVT Header

Major Vector Header
00 32 | Length of major vector
00 25 | Link Statistics major vector

Data Link Traffic Counters Subvector
2E9A | Data Link Traffic Counters subvector
04 | DLC type: token ring
01 or 02 | Statistics type: link counter overflow or adapter counter overflow

Token Ring Adapter Log Information and Counters
hh | Adapter number (01+04)
00 | Reserved
hh | Line error
hh | Internal error
hh | Burst error
hh | ARI/FCI error
hh | End delimiter
00 | Reserved
hh | Lost frame
hh | Receive congestion
hh | Frame copied error
hh | Frequency error
hh | Token error
00 00 00 | Reserved

DLC SAP Station Information
hh hh hh hh | Count of frames transmitted OK
hh hh hh hh | Count of frames received OK
hh hh hh hh | Count of frames discarded
hh hh hh hh | Lost data
hh hh | Buffer available in SAP

DLC Link Station Information
hh hh | Count of I-frames transmitted
hh hh | Count of I-frames received
hh | Received I-frames error count
hh | Transmitted I-frames error count
hh hh | T1 timer expired count


Alerts Used by Applications, NVAlert, and NVRunCmd

Application programs and the NVAlert and NVRunCmd services can generate alerts using the Common Service Verb (CSV) TRANSFER_MS_DATA. An application or service can supply subvectors, which are required to build an NMVT, or it can supply the complete NMVT; in both cases the completed NMVT will be logged locally, and may also be sent on the connection designated for NetView if one is configured and is active. An application or service can also supply user-defined alert data, in which case the data will be logged locally but cannot be sent.

For information about how the NVAlert and NVRunCmd services work, see the Microsoft SNA Server Administration Guide.


Format for Alerts Used by Applications, NVAlert, and NVRunCmd

An application program or the NVAlert and NVRunCmd services can use the CSV TRANSFER_MS_DATA to issue alerts. The alerts are logged in a log file that can be viewed using the Windows NT Event Viewer, and may also be sent on the NetView connection.

The data supplied to TRANSFER_MS_DATA may be in any of the following formats.

NMVT

The application or service supplies a complete NMVT, including the header information.

ALERT_SUBVECTORS

The application or service supplies the subvectors required for an alert, but without the NMVT header or major vector header. SNA Server adds the header information, as described in the next section.

PDSTATS_SUBVECTORS

The application or service supplies the subvectors required for a Problem Determination Statistics NMVT, but without the NMVT header or major vector header. SNA Server adds the header information, as described in the next section.

USER_DEFINED

The application or service supplies data in its own format. This data cannot be sent on the connection designated for NetView, but is logged in the same way as the other data formats.

The application or service can also request SNA Server to add the Product Set ID subvector (for all data types except user_defined), the Date/Time subvector, or both to the supplied data. The format of these added subvectors is described in the next section.

For all data types, the data (with added headers and subvectors, if appropriate) is logged locally in NMVT format, whether or not a connection has been specified for NetView.

Added Headers and Subvectors

NMVT Header

41 03 8D 00 00 00 00 00

NMVT Header

Major Vector Header
LL LL | Length of Major Vector
00 00 or 00 25 | Alert major vector (for data type alert_subvectors), or Problem Determination Statistics major vector (for data type pstats_subvectors)

Product Set ID Subvector
4D 10 | Product Set ID subvector
00 | Unused field
34 11 | Product ID subvector
0C | Product classification: non-IBM software
08 04 | Software product common level subfield
F0 F2 | Version identifier: 02
F0 F0 | Release identifier: 00
F0 F0 | Modification identifier: 00
20 06 | Software product common name subfield
C4 C3 C1 61 D4 E2 40 C3 D6 D4 D4 40 E2 C5 D9 E5 D9 | Product name: MS SNA Server
00 .. 00 | Name padded with nulls to 30 characters
09 08 | Software product program number subfield
F0 F0 F0 F0 F0 F0 F0 | Product program number: zeros
16 11 | Product ID subvector
03 | Product classification: hardware
13 00 | Hardware Product ID subfield
00 | Format type: undefined
hh...hh | Server: Windows NT-based computer name

Date/Time Subvector |
0A 01 | Date/Time Subvector
08 10 | Local Date/Time subfield
hh | Year — two digits
hh | Month
hh | Date
hh | Hours
hh | Minutes
hh | Seconds


Response Time Monitor

During 3270 emulation, statistics are maintained on the time taken for the host to respond to 3270 client requests. RTM data can be sent to the host for collection and analysis; the 3270 user can also view a graphical display of the spread of response times on a particular 3270 emulation session. The time for the last transaction executed can also be displayed on the status line.

Use SNA Server Manager to choose the way in which response times are measured and classified. RTM statistics for a particular LU are sent to the host that owns that LU rather than being sent on the connection designated for NetView data.


Collecting RTM Data and Sending it to the Host

SNA Server always collects RTM data while 3270 emulation is active. The data for each 3270 LU will then be sent to the host to which the LU is connected under various criteria.

You configure the initial criteria for SNA Server to send RTM data to the host when any of the RTM counters reaches its maximum value, and/or each time a 3270 session ends. (For instructions on configuring the RTM function, see the Microsoft SNA Server Administration Guide.) The RTM counters are reset each time the RTM data is sent in this way.

Although initial criteria apply to all SNA Server LUs, any host can change the criteria for any LU or all LUs it owns, and solicit or reset any LU counters.


Boundaries and Measurement Definition

RTM data is collected by comparing host response times against a series of four boundary values. Each time a host transaction occurs, the response time is compared with the boundary values, and the appropriate counter is incremented. There is a counter for each of the four intervals defined by the boundary values, and an overflow counter for response times above the largest boundary value.

You can change the default boundaries — 0.5, 1, 2, and 5 seconds — using SNA Server Manager. You also can select which of three response time definitions to set as default. For instructions, see the Microsoft SNA Server Administration Guide.

The response time is measured from the time the user presses Enter until one of the following events occurs:

  • The first character of host data reaches the 3270 display.
  • The keyboard is unlocked.
  • The user is allowed to send data.

Again, a host can override the default boundaries and other host response time settings for any LU or all LUs it controls. (For more information, see "Host Modification of RTM Parameters" later in this chapter.)


Local Display

You can use SNA Server Manager to allow a 3270 user to view the last transaction time on the status line and a graphical display of the response times for each 3270 display session. For instructions, see the Microsoft SNA Server Administration Guide. Again, the host can override this ability to view the RTM data locally.


Reuse of LUs by Different Users

Response times are recorded for a specific LU rather than for a specific 3270 session. This means that if a 3270 session ends and another session (of the same or a different 3270 user) then uses the same LU, the response time counters will include responses from the previous session as well as those from the new session. This does not happen, however, if the RTM counters were reset before the new session began to use the LU (the counters are reset when the host requests that they be reset or when RTM data is sent unsolicited by SNA Server). When hosts request RTM data they typically also request that the counters be reset.

If you want to ensure that the RTM data displayed relates only to the current 3270 session, you should select the RTM Data Sent at End-of-Session checkbox when configuring RTM parameters for SNA Server. This will ensure that the RTM counters are reset at the end of each 3270 session and will therefore be 0 at the start of each 3270 session. The host can, of course, override this setting.


Host Modification of RTM Parameters

Although you can configure the RTM boundaries and definition that you want to use on your server, the host can override these configured values, either for an individual 3270 LU or for all LUs it controls. The host can also specify whether to permit local display of RTM data, and, when SNA Server sends RTM data, it can disable collection of RTM statistics completely.


Lost-Data Indicator

When SNA Server sends RTM data to the host, it can indicate to the host that RTM data may have been lost (that is, some host response times were not included in the RTM data sent to the host). This indication is sent in the following cases:

  • One of the RTM counters reaches its maximum value, and SNA Server is not configured to send RTM data unsolicited at counter overflow. When this occurs, SNA Server stops recording response times until the host requests the data (or until end-of-session, if unsolicited sending at end-of-session is configured); the data is sent with an indication that data may have been lost due to counter overflow.
  • When the local server terminates abnormally, RTM data obviously is lost and any connection to the host is terminated. When the connection to the host is started, there is no way of knowing whether the connection was previously terminated by a server failure; therefore, the first RTM data sent to the host after the connection is established includes the lost-data indicator, to indicate that data may have been lost due to failure of the local server.
  • When SNA Server is configured to send RTM data at end-of-session, and a new 3270 session is started before the RTM data for the previous 3270 session on the same LU can be sent, response times for the new session are discarded until the RTM data from the previous session is sent and the counters are reset. When RTM data is next sent on the new session, it includes the lost data indicator to indicate this condition.


Local Logging of Network Management Data

Data is logged in a Windows NT Event Viewer log file in two ways. First, the data from the alert is logged in a more readable format, using standard log messages. The format is specific to the alert type; for the message numbers used and explanations of the data, see the section in this chapter that relates specifically to that type of alert.

If a connection has been designated for carrying NetView data and the server that owns the connection is active, the alert NMVT containing the data is also logged in NMVT format as it would be sent. The NMVT appears as message 540 followed by message 541. Note that this logging occurs before SNA Server attempts to send the NMVT; the log is therefore no guarantee that the NMVT is sent successfully.

Additional information about local logging of alert information is presented in the section of this chapter that relates specifically to that type of alert.


Chapter 5 Host Security Integration Architecture

Host Security Integration is a new feature in SNA Server 3.0. It lets you store passwords from multiple operating system environments in a central location, providing security and ease of use for the end-user.

Host Security Integration is composed of three installable components: the Host Account Cache, Password Synchronization, and Security Integration Services. The three services provide users with a simplified logon and maintenance of the many passwords they may need to access Windows NT and host security domains. This chapter provides an in-depth look at Host Security Integration and its internal structure.


Introduction

An enterprise computing environment may include various operating systems such as Windows NT, UNIX, AS/400, and mainframes. Each computing environment has its own security database that defines access rights within the environment. Users are represented by an account name and corresponding password. A user working within this type of network structure may have several different passwords to gain access to each system.

When there is no coordination between the computing environments, the burden is on the user to remember several different account names and passwords. The passwords for each account may not be, and probably aren't, the same. This process can be especially difficult when some accounts are used infrequently.

Another problem is that each computing environment imposes its own password maintenance policies, such as password length and the length of time for which a password is valid. These policies may not be, and probably aren't, coordinated between the computing environments.

Host Security Integration addresses the problem by providing secure storage for the user's host accounts, tools for maintaining the same password in all

environments, and automatic logon to SNA host computers in an enterprise computing environment. This approach coordinates existing host security databases, rather than forcing a migration to a single, shared security database.


Domains

Host Security Integration uses the concept of "security domain" to manage user accounts. A security domain is a set of systems for which a given user account is valid. A security domain may consist of several servers, such as a Windows NT domain, or it may consist of a single SNA host computer. In another, less common configuration, several SNA host computers could form a single security domain if they implement a shared user database.

A host security domain is a collection of systems that share the same user database. The SNA Server administrator defines the boundaries of the host security domain by specifying the SNA Server connections to host computers. The host security domain name should relate to the collection of host computers and can be anything you choose; no host resource name needs to be matched.

When defining a host security domain, two synchronization options apply separately to user IDs and passwords. "Replicated" uses the same user ID or password in all security domains (Windows NT and host computers). "Mapped" allows you to have a different user name and password in each security domain, with the Host Account Cache maintaining the association. For example, a common configuration is the mapping of user IDs and replication of passwords. This allows you to have the same password but different user names on various host computers. During creation of the host security domain, SNA Server Manager creates a Windows NT group with the same name as the host security domain for subsequent use in enabling users.


Account Mapping

Users who need to establish connections with host computers via SNA Server are assumed to have a Windows NT account. In each host security domain, the Windows NT account can be associated with just one host account. If password synchronization is enabled, a particular account can only be related to a single Windows NT account, so password changes on that account from the host applies to only a single Windows NT account.

The association between accounts is relational; that is, the Windows NT account and the associated host computer account do not need to be spelled the same.

The host account cache can store host account names and password of any length; however, SNA host computers generally impose a limit of eight to 10 characters.


Password Synchronization

Password synchronization automatically updates passwords so they are the same for associated accounts in all configured security domains. The user, or a privileged administrator, can initiate a password change on any host or Windows NT computer, and the password synchronization feature will apply the change to the rest of the security domains.

Password synchronization must be configured by the system administrator before use. Synchronization changes can be sent in both directions or limited to only one direction. In addition, a user can selectively enable synchronization for only some of his or her host computer accounts.

Generally, specific third-party software must usually be installed on host computers for password synchronization to work. The exception is AS/400s running V3R1 or later, for which SNA Server provides built-in support for unidirectional synchronization, applying Windows NT changes to the AS/400. It can be enabled on Windows NT or the AS/400 without any additional host code.

For password synchronization to work in a Windows NT security domain, the user must be running on a 32-bit platform and must be logged into the Windows NT domain. Alternatively, the Windows NT security administrator can initiate a password change for the user.


Remote Password Management

An end user tool is provided to manage Windows NT and host computer accounts. The UDConfig tool allows the user to initiate a host password change directly from the client computer without being logged into the host computer. UDConfig is discussed in detail later in this chapter.


Automatic Logon for APPC

SNA Server supports automatic logon for APPC applications communicating with mainframes and AS/400 computers. This feature operates by providing the associated host security domain username and password in the APPC conversation startup request. In addition, this feature also provides the host username in the 5250 session startup program initiation parameter (PIP) data. This allows the user to bypass the AS/400 logon screen for 5250 terminal sessions.

The automatic logon only applies to invoking transaction programs (TPs) initiated in the Windows NT domain. The application must run on either SNA Server or any native client of SNA Server. The user must be logged into the Windows NT domain.

Automatic logon applies to any WinAPPC or WinCPIC application, whether it is delivered by a third party or locally developed. To start automatic logon, the application must invoke an APPC conversation with the program-provided security (see AP_PGM in the Microsoft SNA Server APPC Programmer's Guide). It then must provide the value "MS$SAME" for both the APPC user name and password. SNA Server will replace these keywords with actual host account information when it sends the conversation startup request to the host computer.

Future versions of SNA Server will include automatic logon for 3270 and other dependent LU applications. They will also include invoking APPC TPs on Windows NT running in the Windows NT account associated with a host account used in the conversation startup.


Host Security Integration Components

Host Security Integration is comprised of components packaged as three setup options. Each one works with the Windows NT primary domain or resource domain. These include:

  • Windows NT Account Synchronization Service
  • Host Account Synchronization Service
  • Host Account Cache

Figure 5.1 This figure shows the Host Security Integration components and where they may reside in a security domain.

These services are installed using two methods. The Windows NT Account Synchronization Service and the Host Account Cache are installed using the Host Security Setup located on the SNA Server CD-ROM. The Host Account Synchronization Service is installed during SNA Server Setup. The latter is one of the available options in the Microsoft SNA Server - Select Components dialog box. For more information see the Microsoft SNA Server Getting Started.

This section describes each of the services and the underlying components that are installed during Setup.


Windows NT Account Synchronization Service

This option must be installed on the primary domain controller of the Windows NT domain in which user accounts are defined. It may also be installed on all backup domain controllers in the domain, but the components installed will be inactive until the server is promoted to a primary domain controller.

If user accounts are defined in multiple top-tier domains, the option must be installed on the primary domain controller in each domain.

During Setup, you are prompted for either the primary or backup role of the service. Only one instance of the Windows NT Account Synchronization can be designated as primary; all others must be backup servers. A backup server can be used for password synchronization of Windows NT accounts defined in that domain. The only way to promote or demote the role of this component is by using the Registry to change the entry on the primary and backup SNA Server computers. For more information about the Registry and where to change this information, see Chapter 8 of this manual.

Setup installs the SNAPWCHG.DLL and the SNAPMP service. These are discussed in greater detail below.

SNAPWCHG.DLL

This DLL intercepts password changes for the user accounts defined in the Windows NT domain, regardless of who initiates the change. The DLL is always active to provide notice of password changes for Windows NT accounts in that domain, regardless of the designated role of the server.

Two Registry entries record where the passwords are changed. One lists the Windows NT domain name and the other is the complete path name for the SNAPWCHG. Both of these Registry entries are described in detail in Chapter 8.

SNAPMP Service

The SNAPMP service, also known as the Windows NT Account Synchronization Service, is referred to in this chapter as the Password Management Process, or PMP. It coordinates all updates to the host account cache(s) in the resource

domains and coordinates all the password synchronization activities in the Windows NT and host security domains.

When the service is configured as a primary SNAPMP, the password management process (PMP) registers itself with the master Host Account Cache in all resource domains. PMP will not complete initialization and start normal operation until it has registered in each configured domain. This prevents communication problems from causing inconsistent updates being applied to the Host Account Cache(s).

When the service is configured as a backup PMP, the PMP service starts, determines that it is a backup, and then terminates. This is correct and normal operation.

The SNAPMP service must be installed to run in a security administrator's account. This service must have sufficient privileges to change the password of any user account defined in the domain. When there are several primary domain controllers, SNAPMP must have sufficient privilege to change user accounts in any of the domains.


Host Account Synchronization Service

During SNA Server Setup, the SNAHOSTPROCESS and Host Security Interface DLLs are installed if the Host Account Synchronization Service is included as one of the installation options.

Account Synchronization is only installed to support automatic password synchronization. This service is not necessary if you use single sign-on with manual password update, in which the administrator or users store host account information in the Host Account Cache via Host Account Manager (UDConfig).

This service is generally installed on SNA Server computers. Its operation is not dependent on SNA protocol; however, third-party Host Security Interface DLLs may be. This service must run in the same account as the SNAPMP service.

SNAHOSTPROCESS Service

This Setup option installs a single Windows NT service, SNAHOSTPROCESS, also known as the Host Account Synchronization Service. This Windows NT service supports the Host Security Interface API, MDSI (Multi-Domain Synchronization Interface). Host Security Interface DLLs are written by third-party vendors to notify Windows NT of host password changes initiated on the host and to notify host computers of password changes initiated by Windows NT.


Host Account Cache

This component is installed in Windows NT resource domains. The resource domain contains either SNA Server computers or machine accounts for users who

will use this service. Setup prompts you to define the role of the Host Account Cache as master or backup. A master host account cache is installed on the Primary Domain Controller of the resource domain(s). A backup host account cache can be installed on backup domain controllers or on SNA Server member servers.

SNADATABASE Service

This Windows NT service is also known as Host Account Cache. As the name implies, this service implements the database of host accounts associated with Windows NT accounts. It also maintains a dynamic table of network locations for all other host integration service components.

Each Windows NT domain with Host Security Integration installed has a master copy of the host account cache. In the master role, it performs two functions: it is the resource locator within its Windows NT domain for SNAHOSTPROCESS, SNA Server, UDConfig, and the SNAPMP to locate each other; and it receives updates from SNAPMP and coordinates the updates with all the backup copies of the host account cache.

In backup role, the host account cache maintains a local copy of the user database that can be maintained for backup purposes only, or to eliminate network traffic for single sign-on lookups when installed on the same machine as SNA Server.

When the backup host account cache first activates, it locates the master host account cache and downloads a complete copy of the user database, providing synchronization with the master copy. If the backup cannot locate the master or cannot complete the copy, it will use the prior local copy and log a warning to the event log.

STI.DLL

This DLL provides the common communication routines used by all the other components of Host Security Integration. The Remote Procedure Call (RPC) facility is used for communications, with encryption specified for security. RPC is an intersystem communications standard provided by Windows NT.

For more information about the encryption capabilities of Host Security Integration, see the security section of this chapter.

UDConfig

UDConfig is the interactive tool used by system administrators and end users to manage individual user mapping in the host account cache. When run by a user with administrative privilege, UDConfig can manipulate any user record in the host account cache, but when run by an unprivileged Windows NT user, it can only change that user's record. UDConfig is supported on 32-bit clients only.

UDConfig performs the following functions:

It specifies the host account associated with individual Windows NT accounts in each host security domain.

It specifies individual user preferences (if permitted by the administrator) for replicated or mapped account names and passwords in the host security domain.

The Apply button sends a password change to some or all of the host security domains in which the user has a host account, as well as the host account cache. UDConfig cannot initiate a Windows NT password change directly. However, a change sent to a host computer may update the Windows NT password indirectly if the passwords are replicated and the administrator has enabled password synchronization in both directions with the host computer.

The Update Cache button sends changes to the host account cache, but not to any security domain. This is used to initialize the user's record just after the account is added to a host security domain, and to recover from any failures in the synchronization process that might occur.

SNA Server Node

When a client connects to an SNA Server computer for an LU session and the client-server protocol supports Windows NT authentication, the node starts monitoring the session data for the appearance of host account replacement tokens. These are strings starting with the characters "MS$SAME" that can appear where the host needs to see actual host account information. In APPC sessions, these strings can only appear as conversational security subfields in an LU6.2 Attach message, though they can appear elsewhere in LU0-3 sessions.

For a step-by-step description of the single sign-on process the section "Automatic Logon" later in this chapter.


Host Security Integration Operation

Host Security Integration is implemented through a series of activities: creating a host security domain, enabling users, associating connections with security domains, enabling password synchronization, providing automatic logon, and recording failure modes and recovery.


Creating a Host Security Domain

The administrator defines a host security domain using SNA Server Manager in a Windows NT resource domain containing SNA Server computers. If the same host security domain is defined in multiple SNA Server subdomains, it must be defined with the same name and consistent properties in each subdomain.

When SNA Server Manager creates the host security domain, it sends a message to the primary host account cache in the Windows NT domain and it creates a local group in the Windows NT user database. Properties of the host security domain, including the checkboxes Allow User to Override, Mapped, and Replicated, are stored in the Host Account Cache and not in the SNA Server configuration file.


Enabling Users

Windows NT users must be enabled before they can participate in security integration. The list of Windows NT users who are enabled for the given host security domain is stored in the Windows NT user database. When the host security domain is created, SNA Server Manager also creates a Windows NT local group using the same name as the Windows NT domain. To enable a user in a given security domain, this group must be added to the user's account, or to a Windows NT group of which the user is already a member. The group can be added to the user's account by any the Windows NT User Manager or any other means supported by Windows NT.

Enabling a user does not create a user record in the host account cache. The administrator or the end-user must run UDConfig to create and initialize the record after enabling the account.


Associating Connections with Security Domains

Since the user may have different host accounts in several host security domains, SNA Server must be able to choose the appropriate host account for single sign-on when the user opens a session. Therefore, an SNA connection defined in SNA Server Manager can be assigned to a host security domain. The administrator uses SNA Server Manager to assign the connection using the Insert menu or by dragging a connection to a host security domain folder. A host security domain can be assigned an unlimited number of connections, but each connection can be a member of only one host security domain.

When the client chooses an LU resource (alias or pool), the client and server perform resource location to determine which connection will support the session, and, based on that determination, from which host security domain the host account information will come.


Enabling Password Synchronization

Figure 5.2 This figure represents bidirectional password synchronization between the Windows NT Account Synchronization, Host Account Cache, Host Account Synchronization and ISV DLLs.

On a local area network, SNAHOSTPROCESS, security integration DLLs provided by independent service vendors (ISVs), and SNAPMP cooperate with each other to support password synchronization. On the host, ISV products are usually required.

Working together, these components support bidirectional password synchronization. Changes made on the host computer can update Windows NT and other host computers. Changes made in the Windows NT security domain are sent to all the host computers.

Host-Initiated Changes

Cooperating software must be installed on the host computer to trap password changes initiated by users logged into the host computer. This software is available from third-party vendors; a list of currently available solutions is located in the Companion Product Catalog on the SNA Server 3.0 CD-ROM.

As described under SNAHOSTPROCESS, the security integration DLL is initialized for a given host security domain when that service starts. The DLL uses any proprietary protocol, not necessarily SNA, to establish a session with the host computer. Once the session is started, the host computer will send notification of changes that are made in the host security domain to the DLL.

The third-party vendor DLL forwards the host-initiated change to SNAHOSTPROCESS. Then, SNAHOSTPROCESS uses the resource location of the master SNADATABASE to find the network address of the primary SNAPMP. After SNAPMP is located, SNAHOSTPROCESS sends the host-initiated change to SNAPMP via encrypted RPC. Once SNAPMP receives the change, it drives the execution of the change in all affected security domains. The process it uses is the same regardless of the origin of the change.

Windows NT-Initiated Changes

SNAPWDCHG.DLL is installed on the primary domain controller of the Windows NT domain or domains that support user accounts. It is registered with the Security Account Manager (SAM) in those domains to receive notice of password changes that arise in the Windows NT domain, regardless of how the change was initiated. SNAPWDCHG.DLL uses Registry information provided by Setup to locate the master SNADATABASE in a resource domain. It uses resource location of the master SNADATABASE to locate the primary SNAPMP.

SNAPWDCHG.DLL sends the Windows NT-initiated change to the SNAPMP, via encrypted RPC. Once SNAPMP receives the change, it drives the execution of the change in all affected domains. The process it uses is the same, regardless of the origin of the change.

UDConfig-Initiated Changes

UDConfig can also initiate password changes. It collects change information using a graphical interface provided to the end user.

UDConfig uses the resource location of the master SNADATABASE to find the network address of the primary SNAPMP. It then sends the user-initiated change to SNAPMP via encrypted RPC. Once SNAPMP receives the change, it drives the execution of the change in all affected domains. The process it uses is the same, regardless of the origin of the change.

SNAPMP Completion of Changes

When the primary SNAPMP receives notice of a requested change, it forms a global view of the user's mapping for all the domains, determines which agents must be notified of the change, and proceeds to notify each one. The following can be notified:

  • SNADATABASE in each domain.
  • The Windows NT domain in which user accounts are defined.
  • The host security domains.

Setup creates Registry information to identify all the resource domains containing master SNADATABASE components.

SNAPMP sends a query to each SNADATABASE to gather the user information in all host security domains that are defined. If the change was initiated by the host, the lookup key is the host account within the host security domain. If the change was initiated by UDConfig or Windows NT, the lookup key is the Windows NT account and domain. In either case, SNADATABASE returns the same format record.

SNAPMP then consolidates the information into an updated user record and then sends it to each master SNADATABASE in each resource domain.

If the user has configured a replicated password using the Use Windows NT Password checkbox in UDConfig, the change will affect Windows NT as well as the host security domains. To change a Windows NT password, SNAPMP uses the Win32 API to perform the password change directly. This operation requires that SNAPMP itself run in a Windows NT account that has security administrator privilege in all Windows NT domains that support user accounts. Generally, the change will affect host passwords in host security domains. However, UDConfig changes may not: The user can request that only the Host Account Cache be updated by clicking the Update Cache button. Alternatively, the user can specify that a password change be sent to only one host security domain by clicking the Apply button when changing mapped rather than replicated passwords. SNAPMP determines which host security domains must be notified of the change.

SNAPMP uses resource location to find the SNAHOSTPROCESS that supports that host security domain, and then sends an update to SNAHOSTPROCESS for the host security domain. SNAHOSTPROCESS passes the change across the third-party API to the host security integration DLL, which then passes it on to the host computer. The host computer then responds with a status indication of the successful change and sends it to SNAPMP. If an error occurs in the change for a single host security domain, SNAPMP will log the failure, but will not retry the operation.


Automatic Logon

Figure 5.3 Graphical representation of automatic logon.

When a user activates an SNA application on the client computer, it works with the SNA Server subdomain to perform resource location to determine which SNA Server computer and connection to use to open the LU session.

The SNA application on the client computer provides a replacement keyword as a placeholder for security information during session initiation. The format depends on the type of LU session established. For example, the string "MS$SAME" is used for APPC or C-PIC applications.

The SNA Server (or node) detects the replacement keyword and determines the Windows NT user name under which the client is logged on. This step limits automatic logon support to users running native client-server sessions, since only these sessions support Windows NT authentication. For example, TN3270 is not supported because the TN server cannot determine the client's Windows NT user name.

The node uses resource location to locate the host account cache ¾ either a backup up SNADATABASE service running on the same machine as SNA Server

or the master host account cache in the Windows NT domain running SNA Server. The node sends a lookup message to the host account cache. The request includes the Windows NT user name and host security domain name. It requests the corresponding host account name and password.

The SNADATABASE service checks that the Windows NT account exists in the host account database, and that the account is still a member of users group in the Windows NT domain representing the host security domain. If any of these checks fails, the user record is purged from the host account cache. If all checks pass, the SNADATABASE service returns a reply containing the host account name and password to SNA Server, using encrypted RPC. SNA Server substitutes the host account name and password into the SNA data stream and the host computer sees a regular session start up request containing the host account information.


Failure Modes and Recovery

SNAPMP does not currently exhibit a fully transactional operation If a change cannot be completed by an agent, SNAPMP will complete the processing in the agent that can complete the change.

In addition, it does not retry a failed operation, though it generally logs a message about the failure. It is possible that changes will not be complete and that a manual update of the host account cache will be required to recover.


Security

Network operating system security is an important aspect of all computer environments. This section describes the encryption used by SNA Server Host Security Integration.

Windows NT and RACF (on the mainframe) protect password information for their own user accounts through the use of a one-way cipher and do not store the user's clear-text password. Theoretically, there is no way to recover the original password from the one-way cipher text in a reasonable length of time. However, the host security integration feature must produce the host password in clear text for the host computer session and needs to use a reversible encryption for the host account cache. To protect this information from individuals trying to break into the system, it uses very strong encryption: RC-4, with 128-bit keys.

RC-4 with 40-bit keys is the strongest encryption method currently permitted for export by the United States government for bulk encryption applications. Since the Host Account Cache stores only data on personal identification, the export limitations do not apply and the implementation using 128-bit keys is freely exportable.


Chapter 6 Printer Definition Files

Host Print Service lets you specify the capabilities of a printer to override the defaults provided by the Windows NT printer driver.

By default, jobs submitted by Host Print Service to a Windows NT print queue rely on the printer's Windows NT driver to send to the physical printer the data required to perform such formatting tasks as breaking lines and starting a new page.

Applications that bypass the formatting function of the Windows NT printer driver can use codes specified in a printer definition file to control the physical printer for a particular printer session under Host Print Service. To use the file, open the properties page of the printer session, click the Printing tab, select PDT, and then type the fully qualified path of the file in the box. For more information about using the PDT file, click Help on the printer session properties dialog box.

Creating a printer definition file consists of two steps: First, you create a source text file that defines the codes that can be used to control the printer. Second, you run a program to compile the information in the text file into a binary file that can be used by Host Print Service.


Creating the Source Text File

You can use any text editor (such as Notepad) to create the source text file. The conventional file extension for the source text file is .PDF.

The PDF file consists of two sections:

  • The macro definition section
  • The parameter definition section

All text bounded by the C-language comment markers (/* and */) is treated as comments and ignored by the compiler.

The next two sections describe the PDF sections currently supported by Host Print Service.


Macro Definition Section

The macro definition section is bounded by BEGIN_MACROS and END_MACROS statements and consists of lines with the following syntax:

macro_name EQU control_character_list

The macro name can be any alphanumeric string that does not contain spaces, and the control character list consists of one or more two-digit hexadecimal values representing the data to be sent to the printer.

For example, the following macro defines the NUL character:

NUL EQU 00

See "Sample Source Text File" below for an example macro definition section.


Parameter Definition Section

The parameter definition section immediately follows the macro definition section and consists of one or more lines with the following syntax:

parameter_name = value_list

The parameter name can be any character string that does not contain spaces. The compiler ignores parameter names not supported by Host Print Service.

The value list can be empty or can contain one or more of the following:

  • A three-digit decimal value
  • A two-digit hexadecimal value
  • The name of a macro specified in the macro definition section

For example, the following shows a parameter defining the control sequence to be sent to the printer to begin a new line:

NEW_LINE = CRR LFF

In this example, CRR and LFF are the names of macros specified in the macro definition section.

Host Print Service currently supports the following parameters (definitions of unsupported parameters are ignored):

Parameter Name | Description
MAXIMUM_PRINT_POSITION | Maximum number of columns; must be 80 or 132
DEFAULT_LPI? | Default number of lines per inch; must be 6 or 8
START_JOB | Control sequence to be sent at the start of a print job
END_JOB | Control sequence to be sent at the end of a print job
CARRIAGE_RETURN | Control sequence for a carriage return
LINE_FEED | Control sequence for a line feed
FORM_FEED | Control sequence for a form feed
NEW_LINE | Control sequence for a new line
SET_6_LINES_PER_INCH | Control sequence to specify 6 LPI
SET_8_LINES_PER_INCH | Control sequence to specify 8 LPI
START_HIGHLIGHT_INTENSE | Control sequence to begin bold printing
END_HIGHLIGHT_INTENSE | Control sequence to end bold printing
START_HIGHLIGHT_UNDERLINE | Control sequence to begin underline printing
END_HIGHLIGHT_UNDERLINE | Control sequence to end underline printing


Sample Source Text File

The following sample PDF file, HPLJ2.PDF, is provided on the SNA Server CD-ROM in the \platform\SYSTEM\PRINTSRV directory.

/*****************************************************************************/
/*                                                                           */
/* Printer Definition File for HP Laserjet series II and DeskJet             */
/*                                                                           */
/*****************************************************************************/

/*****************************************************************************/
/*                                                                           */
/* Macro Definition Section                                                  */
/*                                                                           */
/* Macros can be defined to be used later in the file as shorthand for       */
/* control code sequences.                                                   */
/*                                                                           */
/* This section of the file is de-limited by the BEGIN_MACROS and END_MACROS */
/* markers. The format of a macro definition is:                             */
/*                                                                           */
/*         <macro name> EQU <list of bytes>                                  */
/*                                                                           */
/* where <list of bytes> consists of decimal and/or hex values separated by  */
/* spaces. A decimal value is 3 digits long (with preceding zero if          */
/* necessary e.g. 023) and a hex value is 2 digits long.                     */
/*                                                                           */
/*****************************************************************************/
BEGIN_MACROS
LFF              EQU 0A               /* line feed                           */
FFF              EQU 0C               /* form feed                           */
CRR              EQU 0D               /* carriage return                     */
P17              EQU 1B 26 6B 32 53   /* 16.7 pitch-characters per inch      */
CS1              EQU 1B 28 38 55      /* Roman 8 char set 1                  */
EC1              EQU 1B 28 30 4E      /* ECMA-94 Latin 1 char set 1          */
SUL              EQU 1B 26 64 44      /* start underline                     */
CUL              EQU 1B 26 64 40      /* cancel underline                    */
LL6              EQU 1B 26 6C 36 44   /* set line length 6 lines per inch    */
LL8              EQU 1B 26 6C 38 44   /* set line length 8 lines per inch    */
SBP              EQU 1B 28 73 31 42   /* start bold printing                 */
CBP              EQU 1B 28 73 30 42   /* cancel bold printing                */
END_MACROS

 /*****************************************************************************/
/*                                                                           */
/* Following the macro definitions, session parameters and control codes     */
/* for the printer can be specified.                                         */
/*                                                                           */
/* These parameters are specified in the following way:                      */
/*                                                                           */
/*        <parameter name> = <value>                                         */
/*                             or                                            */
/*                           <control code sequence>                         */
/*                                                                           */
/* where <value> is a macro, (2-digit) hex or (3-digit) decimal value        */
/* and <control code sequence> is a list of macros and/or hex and/or         */
/* decimal values separated by spaces.                                       */
/*                                                                           */
/*****************************************************************************/

/*****************************************************************************/
/* Session Parameters                                                        */
/*****************************************************************************/
MAXIMUM_PRINT_POSITION = 132          /* printed characters per line         */
DEFAULT_LPI? = 006                    /* default lines per inch              */

/*****************************************************************************/
/* Control Codes                                                             */
/*****************************************************************************/
START_JOB = CUL CBP EC1               /* switch to ECMA-94 Latin 1 char set  */
END_JOB = CUL CBP CS1 FFF             /* return to Roman8 char set, then FF  */

CARRIAGE_RETURN = CRR                 /* carriage-return                     */
NEW_LINE = CRR LFF                    /* new line                            */
LINE_FEED = LFF                       /* line feed                           */
FORM_FEED = FFF                       /* form feed                           */

SET_6_LINES_PER_INCH = LL6            /* code for 6 lines per inch           */
SET_8_LINES_PER_INCH = LL8            /* code for 8 lines per inch           */

START_HIGHLIGHT_INTENSE = SBP         /* start bold printing                 */
END_HIGHLIGHT_INTENSE = CBP           /* end bold printing                   */
START_HIGHLIGHT_UNDERLINE = SUL       /* start underline printing            */
END_HIGHLIGHT_UNDERLINE = CUL         /* end underline printing              */

/*****************************************************************************/
/* End of Definition File                                                    */
/*****************************************************************************/


Compiling the Source Text File

Once you have created the source text file, the next step is to compile the file using the Pdfcomp (PDFCOMP.EXE) utility located in the \platform\SYSTEM\PRINTSRV directory of the SNA Server CD-ROM. To run Pdfcomp, enter the following at the Windows NT command prompt:

pdfcomp input_file output_file

You must specify the full name (including file extensions) of the input and output files.

For example, to compile the sample PDF file, copy PDFCOMP.EXE and HPLJ2.PDF to a directory on the server's hard drive, start a command prompt, change the current directory to the directory containing the copied files, and enter the following at the prompt:

pdfcomp hplj2.pdf hplj2.pdt

This will create the binary PDT file in the current directory. Specifying this file in the properties of a printer session will allow Host Print Service to send preformatted data to the printer, bypassing the formatting function of the Windows NT printer driver.


Chapter 7 Sample Host Definitions

This appendix presents sample host definitions for SNA Server connections to IBM® S/370 (host) systems. The samples show configuration values for SNA Server connections of the following kinds:

Connection type | Connection use | Host system
Token ring | 3270 emulation | Virtual Telecommunications Access Method (VTAM)
SDLC switched | 3270 emulation | VTAM
SDLC leased | 3270 emulation | VTAM
X.25 | 3270 emulation | VTAM
Any type | LU 6.2 | Customer Information Control System (CICS)

Note The VTAM listings in this appendix omit the column 72 continuation character.

For more information about VTAM, NCP, CICS, with respect to 3270 and APPC as well as link type specific definitions on the host see Part Seven, "Host and AS/400 Configuration Parameters," in Microsoft SNA Server Administration Guide.


VTAM Sample Definitions for 3270

This section presents sample VTAM definitions (version 3.2.2) for SNA Server connections to an IBM 9370 host system for 3270 emulation. There are samples for SDLC, for token ring, and for X.25 connections.


Token Ring Definition

Table 7.1 shows a VTAM definition for a connection between an SNA Server and an IBM 9370 host computer across a token ring local area network (LAN).

Table 7.1 VTAM Token Ring Definitions

Name | Description | Parameters
LANODE | VBUILD | TYPE=LAN
R01100 | PORT | CUADDR=100,MACADDR=400001701100, LANCON=(5,2),MAXDATA=2012, MAXSTN=32,SAPADDR=04
G01100 | GROUP | DIAL=YES,ISTATUS=ACTIVE,LNCTL=SDLC
L01100A | LINE | CALL=INOUT
P01100A | PU | MAXLU=254
L01100B | LINE | CALL=INOUT
P01100B | PU | MAXLU=254
SWLAN | VBUILD | TYPE= SWNET,MAXGRP=5,MAXNO=12
SERVER01 | PU | ADDR=C1,IDBLK=05D,IDNUM=00001, ANS=CONTINUE,MAXDATA=265, MAXOUT=7,MAXPATH=7,PACING=0, VPACING=0,SSCPFM=USSSCS, LANACK=(0,0),LANCON=(5,2), LANINACT=4.8,LANRESP=(5,2), LANSDWDW=(7,1),LANSW=YES, MACADDR=4000000000FD,PUTYPE=2, DISCNT=(NO),ISTATUS=ACTIVE, SAPADDR=04
E01100A | PATH | DIALNO=0004400001701100, GRPNM=G01100,GID=1,PID=1,USE=YES
T0110000 | LU | LOCADDR=002,DLOGMOD=D4C32782
T0110001 | LU | LOCADDR=003,DLOGMOD=D4C32782
T0110002 | LU | LOCADDR=004,DLOGMOD=D4C32782
T0110003 | LU | LOCADDR=005,DLOGMOD=D4C32782
T0110004 | LU | LOCADDR=006,DLOGMOD=LU33286S

Table 7.2 defines key parameters shown in Table 7.1.

Table 7.2 VTAM Parameter Descriptions for Token Ring

VTAM parameter | Corresponding SNA Server parameter | Description
IDBLK= | First three digits of Local Node ID (basic connection setting) | A three-digit hexadecimal value that, together with IDNUM, identifies the SNA Server. The values 000 and FFF cannot be used; these values are reserved.
IDNUM= | Last five digits of Local Node ID (basic connection setting) | A five-digit hexadecimal value that, together with IDBLK, identifies the SNA Server.
MAXDATA= (in the PU definition for SERVER01) | Max BTU Length (advanced 802.2 setting) | The maximum length of a basic transmission unit (BTU) sent or received; BTUs are also known as I-frames. Max BTU Length should be less than or equal to MAXDATA.
MACADDR= in the PORT definition | Remote Network Address (basic 802.2 setting) | The media access control address, a 12-digit hexadecimal address. The Remote Network Address (MACADDR) shown in Table 7.1 is 400001701100.
SAPADDR= in the PU definition | Remote SAP Address (advanced 802.2 setting) | The system access point address, a two-digit hexadecimal number, a multiple of 4, between 04 and EC. The Remote SAP Address shown in Table 7.1 is 04, the default value. This value is recommended for most installations.
LOCADDR= in the LU definition | LU Number | The LU local address at the PU. For independent LUs that communicate with a host, the LOCADDR parameter must be set to 0. For dependent LUs with VTAM, the LOCADDR must be at least 2. Also, for dependent LUs, the LU Numbers set in SNA Server must match the LOCADDR values on the host. The LU Numbers range from 002 to 006 in Table 7.1.

The GRPNM value shown in the sample in Table 7.1 is a group name; group names must match the label of a VTAM group definition. The DLOGMOD values shown in the sample are the logon mode table entries from the mode table. For descriptions of the group macros used in these samples, and a complete listing of default mode table entries, see the documentation for your IBM product.


SDLC Definition (for Switched and Leased Lines)

Table 7.3 shows a sample IBM 9370 VTAM definition for four SDLC lines. The LLGROUP label shows the VTAM definitions for lines B80 and BB0 of a leased group. The SNAGROUP label shows the VTAM definitions for lines B90 and BA0 of a switched group.

Table 7.3 VTAM Definition for Four SDLC Lines

Label | Operation | Operands
IBMLINE | VBUILD | TYPE=CA
LLGROUP | GROUP | LNCTL=SDLC,DIAL=NO,ACTIVTO=10
L01B80 | LINE | ADDRESS=B80,PAUSE=0.4,REPLYTO=2.0, RETRIES=7
P01B80A | PU | ADDR=C1,DISCNT=NO,PASSLIM=7, PUTYPE=2,MAXOUT=7,USSTAB=AUSSTAB
T01B8002 | LU | LOCADDR=002,DLOGMOD=D4C32792
T01B8003 | LU | LOCADDR=003,DLOGMOD=D4C32792
T01B8004 | LU | LOCADDR=004,DLOGMOD=D4C32792
L01BB0 | LINE | ADDRESS=BB0,PAUSE=0.4,REPLYTO=2.0, RETRIES=7
P01BB0A | PU | ADDR=C1,DISCNT=NO,PASSLIM=7, PUTYPE=2,MAXOUT=7,USSTAB=AUSSTAB
T01BB000 | LU | LOCADDR=002,DLOGMOD=D4C32792
T01BB001 | LU | LOCADDR=003,DLOGMOD=D4C32792
T01BB002 | LU | LOCADDR=004,DLOGMOD=D4C32792
T01BB003 | LU | LOCADDR=005,DLOGMOD=D3C32792
T01BB004 | LU | LOCADDR=006,DLOGMOD=LU33286S
SNAGROUP | GROUP | LNCTL=SDLC,DIAL=YES,MAXLU=20
L01B90 | LINE | ADDRESS=B90,PAUSE=0.4,REPLYTO=2.0, RETRIES=7
P01B90A | PU |
L01BA0 | LINE | ADDRESS=BA0,PAUSE=0.4,REPLYTO=2.0, RETRIES=7
P01BA0A | PU |

Table 7.4 shows the sample IBM 9370 VTAM switched definition for the SNAGROUP label in Table 7.3.

Table 7.4 VTAM Switched Definition for SNAGROUP

Label | Operation | Operands
SWNODE | VBUILD | TYPE=SWNET,MAXGRP=0,MAXNO=0
SWPU1 | PU | ADDR=C1,IDBLK=017,IDNUM=DC006, DISCNT=NO,PASSLIM=2,PUTYPE=2, MAXDATA=265,MAXOUT=2, USSTAB=MSUSSTAB
T01BA000 | LU | LOCADDR=2,DLOGMOD=D4C32782
T01BA001 | LU | LOCADDR=3,DLOGMOD=D4C32782
T01BA002 | LU | LOCADDR=4,DLOGMOD=D4C32782
T01BA003 | LU | LOCADDR=5,DLOGMOD=D4C32782
T01BA004 | LU | LOCADDR=6,DLOGMOD=LU33286S

Table 7.5 describes key parameters shown in Tables 7.3 and 7.4.

Table 7.5 VTAM Parameter Descriptions for SDLC

VTAM parameter | Corresponding SNA Server parameter | Description
ADDR= | Poll Address (advanced SDLC setting) | A two-digit hexadecimal value that identifies the control unit that the host uses to poll.
IDBLK= | First three digits of Local Node ID (basic connection setting) | A three-digit hexadecimal value that, together with IDNUM, identifies the SNA Server. The values 000 and FFF cannot be used; these values are reserved.
IDNUM= | Last five digits of Local Node ID (basic connection setting) | A five-digit hexadecimal value that, together with IDBLK, identifies the SNA Server.
MAXDATA= (in the PU definition for SWPU1) | Max BTU Length (advanced SDLC setting) | The maximum length of a basic transmission unit (BTU) sent or received; BTUs are also known as I-frames.
LOCADDR= | LU Number | The LU local address at the PU. For independent LUs that communicate with a host, the LOCADDR parameter must be set to zero. For dependent LUs with VTAM, the LOCADDR must be at least 2. Also, for dependent LUs, the LU Numbers set in SNA Server must match the LOCADDR values on the host.

The DLOGMOD values shown in the example are the logon mode table entries from the mode table. For a complete listing of default mode table entries, see the documentation for your IBM product.


X.25 Definition

Table 7.6 shows a sample IBM 9370 VTAM definition for X.25 circuits. The X25GROUP label shows the VTAM definitions for switched virtual circuits 001 through 006.

Table 7.6 VTAM Definition for X.25 Connection

Label | Operation | Operands
X25NODE | VBUILD | TYPE=PACKET
PORTA00 | PORT | CUADDR=(A00,A08),NETTYPE=1, CHARGACC=YES,CHARGE=NO, VCALLS=(,,001,006,,),DIALNO=31370023061 MAXOUT=7,NETLEVEL=80,PMOD=8, PLENGTH=256,PWINDOW=3,REPLYT0=3, RETRIES=7
VCPA00 | VCPARMS | LC=(1,6),PWINDOW=3,PLENGTH=256
X25GROUP | GROUP | DIAL=YES,LNCTL=SDLC,CALL=INOUT, ISTATUS=ACTIVE
L01A00A | LINE | ADDRESS=001,AUTO=001, ISTATUS=ACTIVE
P01AOOA | PU | MAXLU=32
L01A00B | LINE | ADDRESS=002,ISTATUS=INACTIVE, AUTO=002
P01AOOB | PU | MAXLU=32
L01A00C | LINE | ADDRESS=003,ISTATUS=INACTIVE, AUTO=003
P01AOOC | PU | MAXLU=32
L01A00D | LINE | ADDRESS=004,ISTATUS=INACTIVE, AUTO=004
P01AOOD | PU | MAXLU=32
L01A00E | LINE | ADDRESS=005,ISTATUS=INACTIVE, AUTO=005
P01AOOE | PU | MAXLU=32
L01A00F | LINE | ADDRESS=006,ISTATUS=INACTIVE, AUTO=006
P01AOOF | PU | MAXLU=32

Table 7.7 shows the sample IBM 9370 VTAM switched definition for the X25GROUP label in Table 7.6.

Table 7.7 VTAM Switched Definition for X25GROUP

Label | Operation | Operands
X25 | VBUILD | TYPE=SWNET,MAXGRP=5,MAXNO=12
USER01 | PU | ADDR=C1,IDBLK=05D,IDNUM=00025, ANS=CONTINUE,MAXDATA=265, MAXOUT=7,MAXPATH=0,PACING=0, VPACING=0,SSCPFM=USSSCS, IRETRY=YES,USSTAB=MSUSSTAB, PUTYPE=2,DISCNT=YES,ISTATUS=ACTIVE
T01A0002 | LU | LOCADDR=002,DLOGMOD=D4C32792
T01A0003 | LU | LOCADDR=003,DLOGMOD=D4C32792
T01A0004 | LU | LOCADDR=004,DLOGMOD=D4C32792
T01A0005 | LU | LOCADDR=005,DLOGMOD=D4C32792
T01A0006 | LU | LOCADDR=006,DLOGMOD=LU33286S

Table 7.8 defines key parameters shown in Tables 7.6 and 7.7.

Table 7.8 VTAM Parameter Descriptions for X.25

VTAM parameter | Corresponding SNA Server parameter | Description
IDBLK= | First three digits of Local Node ID (basic connection setting) | A three-digit hexadecimal value that, together with IDNUM, identifies the SNA Server. The values 000 and FFF cannot be used; these values are reserved.
IDNUM= | Last five digits of Local Node ID (basic connection setting) | A five-digit hexadecimal value that, together with IDBLK, identifies the SNA Server.
DIALNO= in the PORT definition | Remote X.25 Address | An address that identifies an X.25 system. The address consists of from 1 through 15 hexadecimal digits. If a 15-digit address is used, the final 3 digits are used for routing between stations with the same 12-digit address.
MAXDATA= (in the PU definition for USER01) | Max BTU Length (advanced X.25 setting) | The maximum length of a BTU sent or received.
LOCADDR= | LU Number | The LU local address at the PU. For independent LUs that communicate with a host, the LOCADDR parameter must be set to 0. For dependent LUs with VTAM, the LOCADDR must be at least 2. Also, for dependent LUs, the LU Numbers set in SNA Server must match the LOCADDR values on the host. The LU numbers range from 002 to 006 in Table 7.7.


CICS and VTAM Sample Definitions for LU 6.2

This section presents sample definitions for CICS (version 1.6) and VTAM (version 3.2) for SNA Server connections to an IBM host system for LU 6.2 operation.

To configure a CICS host system for LU 6.2 operation with an SNA Server system, you configure the following information at the host:

  • The remote systems with which CICS is able to communicate.
  • The name used by VTAM to communicate with each remote system.
  • The transaction programs (TPs) available on the CICS system.
  • The programming language (PL/I, COBOL, or Assembler) in which each program is written.

This information is configured in CICS and VTAM tables. This section provides sample definitions that show how to configure CICS for LU 6.2 using these CICS and VTAM tables.


CICS Tables

CICS uses the following tables to define LU 6.2 information:

  • Terminal Control Table (TCT) — defines the remote systems to CICS.
  • Program Control Table (PCT) — defines the local TPs to CICS.
  • Program Processing Table (PPT) — defines the load module characteristics to CICS.

The following paragraphs describe these tables, and include sample definitions to illustrate how they are used.

Note These samples assume there are four TPs residing on CICS written in PL/I with the following names: TRAN0, TRAN1, TRAN2, and TRAN3.

Terminal Control Table

The Terminal Control Table (TCT), Table 7.9, defines the remote systems to CICS. Each remote system is specified using a DFHTCT definition, which includes both the name by which CICS knows the system (the SYSIDNT field), and the name by which VTAM knows the system (the NETNAME field).

Table 7.9 Sample CICS Terminal Control Table Entries

Label | Definition | Operands
TP11 | DFHTCT | TYPE=SYSTEM ACCMETH=VTAM, FEATURE=SINGLE,TRMTYPE=LUTYPE62, NETNAME=TPLU6207,SYSIDNT=DC11, MODENAM=LU62,CONNECT=AUTO, BUFFER=256,RUSIZE=256, TRMSTAT=(TRANSCEIVE)
TP12 | DFHTCT | TYPE=SYSTEM ACCMETH=VTAM, FEATURE=SINGLE,TRMTYPE=LUTYPE62, NETNAME=TPLU6208,SYSIDNT=DC12, MODENAM=LU62,CONNECT=AUTO, BUFFER=256,RUSIZE=256, TRMSTAT=(TRANSCEIVE)
TP13 | DFHTCT | TYPE=SYSTEM ACCMETH=VTAM, FEATURE=SINGLE,TRMTYPE=LUTYPE62, NETNAME=TPLU6209,SYSIDNT=DC13, MODENAM=LU62,CONNECT=AUTO, BUFFER=256,RUSIZE=256, TRMSTAT=(TRANSCEIVE)
TP14 | DFHTCT | TYPE=SYSTEM ACCMETH=VTAM, FEATURE=SINGLE,TRMTYPE=LUTYPE62, NETNAME=TPLU620A,SYSIDNT=DC14, MODENAM=LU62,CONNECT=AUTO, BUFFER=256,RUSIZE=256, TRMSTAT=(TRANSCEIVE)

Program Control Table

The Program Control Table (PCT), Table 7.10, defines the local TPs to CICS. Each TP is specified using a DFHPCT definition, which includes the name by which the TP is invoked (the TRANSID field), and the corresponding load module name from the CICS library of TPs.

Table 7.10 Sample CICS Program Control Table Entries

TP Label | Definition | Operands
TRAN0 | DFHPCT | TYPE=ENTRY PROGRAM=TRAN0000, TWASIZE=1000,SPURGE=NO,TPURGE=NO, RSL=00,RSLC=NO,MODENAM=NORMAL, TRANSID=TRAN0
TRAN1 | DFHPCT | TYPE=ENTRY PROGRAM=TRAN0001, TWASIZE=1000,SPURGE=NO,TPURGE=NO, RSL=00,RSLC=NO,MODENAM=NORMAL, TRANSID=TRAN1
TRAN2 | DFHPCT | TYPE=ENTRY PROGRAM=TRAN0002, TWASIZE=1000,SPURGE=NO,TPURGE=NO, RSL=00,RSLC=NO,MODENAM=NORMAL, TRANSID=TRAN2
TRAN3 | DFHPCT | TYPE=ENTRY PROGRAM=TRAN0003, TWASIZE=1000,SPURGE=NO,TPURGE=NO, RSL=00,RSLC=NO,MODENAM=NORMAL, TRANSID=TRAN3
* ****** * PROFILE TO BE USED IN LU6.2 ALLOCATE * ****** *
 | DFHPCT | TYPE=PROFILE, PROFILE=DFHCICSA, INBFMH=ALL,MODENAME=LU62

Program Processing Table

The Program Processing Table (PPT), Table 7.11, defines the load module characteristics to CICS.

Each load module is defined using the DFHPPT definition, which includes the name of the load module (the PROGRAM field), and the language in which the module has been written, for example, PL/I, Assembler, or COBOL (the PGMLANG field).

Table 7.11 Sample CICS Program Processing Table Entries

Definition | Program name | Language
DFHPPT TYPE=ENTRY | PROGRAM=TRAN0000 | PGMLANG=PL/I
DFHPPT TYPE=ENTRY | PROGRAM=TRAN0001 | PGMLANG=PL/I
DFHPPT TYPE=ENTRY | PROGRAM=TRAN0002 | PGMLANG=PL/I
DFHPPT TYPE=ENTRY | PROGRAM=TRAN0003 | PGMLANG=PL/I


VTAM Definitions

Each remote system must be defined to VTAM in its table of Network Addressable Units, called NAUs, using LU definitions (see Table 7.12).

Note that if a LOGAPPL parameter is specified on the LU definition naming the CICS system, CICS will attempt to establish a session to that LU whenever it becomes active. This is necessary if TPs residing in CICS do not use the ALLOCATE verb with RETURN_CONTROL=WHEN_SESSION_ALLOCATED to establish sessions. There must also be a VTAM mode table definition present for LU 6.2, although CICS does not use the values specified here.

Table 7.12 Sample VTAM Network Control Program (NCP) Definition for LU 6.2

Label | Operation | Operands
TPPU62 | PU | ADDR=C1,IBLK=03E,IDNUM=01A1A, IRETRY=YES,DISCNT=NO,ISTATUS=ACTIVE, MAXDATA=265,SSCPFM=USSSCS, MODETAB=MRNDS,USSTAB=USSNDN1, MAXOUT=7,PASSLIM=7,PUTYPE=2
TPLU6207 | LU | LOCADDR=7,DLOGMOD=LU62, USSTAB=USSNOMSG
TPLU6208 | LU | LOCADDR=8,DLOGMOD=LU62, USSTAB=USSNOMSG
TPLU6209 | LU | LOCADDR=9,DLOGMOD=LU62, USSTAB=USSNOMSG
TPLU620A | LU | LOCADDR=A,DLOGMOD=LU62, USSTAB=USSNOMSG

Table 7.13 shows NCP mode table entries for LU 6.2.

Table 7.13 Sample NCP Mode Table Entries for LU 6.2

Label | Operation | Operands
 | MODETAB |
LU62 | MODEENT | LOGMODE=NORMAL
 | . . . |
 | MODEEND |

Note It is recommended that the mode used by LU 6.2 LUs be listed first, as shown by the listing of LU62 in the preceding table.

TP Coding Requirements

To work with CICS, TPs must be coded to specify a SYSID parameter on the ALLOCATE request that matches the defined SYSIDNT parameter configured in the DFHTCT tables. This request must be in the following format:

EXEC CICS ALLOCATE SYSID('DC11')

The SYSID field must match the SYSIDNT field specified for a CICS program by the DFHTCT definition in the TCT. The TCT then uses the NETNAME parameter to refer to a specific LU in the VTAM table of NAUs for use by the TP to communicate with the remote system.


Chapter 8 Registry and Environment Variables for SNA Server

This chapter describes the Registry variables and environment variables that can be set for SNA Server.

In most situations, it is recommended that you leave Registry and environment variables at the default settings. Specifying different values for variables allows you to:

  • Communicate with a host that implements unusual variants of SNA protocols. Changing the Registry and/or environment variables allows for workarounds with such hosts.
  • Use special default values for such settings as timers.
  • Set a variable for an application when the application could not use a standard API call to set that variable.

Important Change Registry and environment variables only if your specific situation makes it appropriate. Changing Registry and environment variables inappropriately can disable SNA Server functionality. In most situations, these variables can be left at default settings.

The variables used to configure an invokable TP are not documented in this chapter. For information about these variables, see Chapter 2 of the Microsoft SNA Server APPC Programmer's Guide, or Chapter 2 of the Microsoft SNA Server CPI-C Programmer's Guide.


Setting Variables on Different Operating Systems

The following table shows how Registry and environment variables are set on a server and on the various types of SNA Server clients. For information about the Windows NT Registry, see the Windows NT documentation. For information about environment variables for the Windows™ version 3.x, MS-DOS®, or OS/2® operating systems, see the appropriate operating system documentation.

Operating system and SNA Server software | Method for setting Registry variables or environment variables
Windows NT with SNA Server or SNA Server client | Change values in the Windows NT Registry by using the Registry editor, REGEDT32.
Windows 95 with SNA Server client | Change values in the Windows 95 Registry by using the Registry editor, REGEDIT.
Windows version 3.x with SNA Server client | Add or change lines in the WIN.INI file.
MS-DOS with SNA Server client | Add or change lines in the SNA.INI file.
OS/2 with SNA Server client | Use set commands, either at the command prompt or in CONFIG.SYS.


Lists of Available Variables

The following table outlines the Registry variables that can be set on a computer running SNA Server. For detailed information about each variable, see the sections that follow.

Table 8.1 Registry Variables for SNA Server

Variable | What is affected
ALLOCINACT:REG_SZ:{ YES | NO } | Allocation of inactive LUs from a pool
ALLOWBBRQE:REG_SZ:{ YES | NO } | Use of begin bracket, exception response
CLEANUP:REG_SZ:{ YES | NO } | Deactivation method for sessions
COMBUF:REG_DWORD:number | Size of buffer pool available
NO4004:REG_SZ:{ YES | NO } | Handling of sense code 4004
NOINITCNOS:REG_SZ:{ YES | NO } | Time at which CNOS negotiation is performed
BINDRETRY:REG_DWORD:number | Retry time-out for BIND attempts for autoactivated sessions
NORETRY:REG_SZ:{ YES | NO } | Retry of BIND
NOTERMSELF:REG_SZ:{ YES | NO } | Termination of 3270 sessions
RENEGLIMITS:REG_SZ:{ YES | NO } | Automatic CNOS renegotiation when a BIND fails
RETRYCNOS:REG_SZ:{ YES | NO } | Automatic CNOS renegotiation when partner resets session limits
SESTIMEOUT:REG_SZ:number | Time at which unused contention winner sessions are deactivated
NONOTIFYRSP:REG_SZ:{ YES | NO } | How SNA Server responds to the lack of a Notify response.
SyncConfigFiles:REG_SZ:{ ON | OFF } | SnaBase: copying of configuration file from primary to backup servers
ACCPTFMT:REG_SZ:{ 0 | 1} | X.25: use of addresses on CALL_ACCEPT
LUWIDSUP:REG_SZ:{ YES | NO } | APPC: support of logical unit of work identifier
application:REG_SZ:localLUalias | CPI-C: the local LU alias to be used by an application
APPCTPN:REG_SZ:TPname | CPI-C: the local TP name
COMTBLG:REG_SZ:filename | CSV: name of file containing Table G (for code conversion)
COMCPT:REG_DWORD:path | CSV: path of code page (for code conversion)
SNAMAXLUALUS:REG_DWORD:number | LUA: number of frames in the protocol window
LOCALLUS:REG_MULTI_SZ:localLUname | No longer used in SNA Server 3.0
COMPOP12:REG_SZ:{ YES | NO } | Suppression of level 12 pop-up warnings
Unique5250Names:REG_SZ:{ YES | NO } | Uniqueness of session IDs for 5250 emulators
FrameType:REG_DWORD:number | DIX or 802.3 framing in an Ethernet LAN; significant when communicating via a router
BufferAuditInterval:REG_DWORD:number | Auditing of buffer pool at regular intervals
DloadMatchTPOnly:REG_SZ:{ YES | NO } | Method for matching requested TP against available TPs
DloadMatchLocalFirst:REG_SZ:{ YES | NO } | Method for matching requested TP against available TPs
ConfigFilePath:REG_SZ:pathname | Path used when the server accesses the local configuration file
NumberOfDevices:REG_DWORD:ports | Number of RAS ports available to SNA Remote Access Service

Table 8.2 outlines the Registry variables that can be set on an SNA Server client running Windows NT. For detailed information about each variable, see the sections that follow.

Table 8.2 Registry Variables for an SNA Server Client Running Windows NT

Variable | What is affected
LUWIDSUP:REG_SZ:{ YES | NO } | APPC: support of logical unit of work identifier
application:REG_SZ:localLUalias | CPI-C: the local LU alias to be used by an application
APPCTPN:REG_SZ:TPname | CPI-C: the local TP name
COMTBLG:REG_SZ:filename | CSV: name of file containing Table G (for code conversion)
COMCPT:REG_DWORD:path | CSV: path of code page (for code conversion)
SNAMAXLUALUS:REG_DWORD:number | LUA: number of frames in protocol window
LOCALLUS:REG_MULTI_SZ:localLUname | No Longer Used In SNA Server 3.0.
COMPOP12:REG_SZ:{ YES | NO } | Suppression of level 12 pop-up warnings
BufferAudit Interval:REG_DWORD:number | Auditing of buffer pool at regular intervals
OtherServers:REG_MULTI_SZ:server1 [server2][ ...] | Access to LUs through servers outside a client's subdomain
SnaBackupDomain:REG_SZ:subdomain | Sponsor connection through an alternate subdomain if the primary subdomain is not available. This variable is also on clients running Windows 95.
BackupServers:REG_MULTI_SZ: | Sponsor connection through alternate sponsor servers if the primary sponsor servers are not available. This variable is also on clients running Windows 95.

Note Tables 8.2 and 8.3 do not include the variables used for configuring an invokable TP. For information about these variables, see Chapter 2 of the Microsoft SNA Server APPC Programmer's Guide or Chapter 2 of the Microsoft SNA Server CPI-C programmer's Guide.

Table 8.3 outlines the environment variables that can be set on an SNA Server client running the Windows version 3.x, MS-DOS, or OS/2 operating systems. For detailed information about each variable, see the sections that follow.

Table 8.3 Environment Variables: Windows version 3.x, MS-DOS, or OS/2

Variable |  | What is affected
LUWIDSUP={ YES | NO } |  | APPC: support of logical unit of work identifier
[ApplicationName] APPCLLU=localLUalias |  | CPI-C: the local LU alias to be used by an application
APPCTPN=TPname |  | CPI-C: the local TP name
COMTBLG=filename |  | CSV: name of file containing Table G (for code conversion)
COMCPT=path |  | CSV: path of code page (for code conversion)
SNAMAXLUALUS=number |  | LUA: number of frames in protocol window
For MS-DOS and Windows version 3.x: LOCALLUS=localLUname For OS/2: COMLUASS={ YES | NO } |  | No longer used in SNA Server 3.0.
COMPOP12={ YES | NO } |  | Suppression of level 12 pop-up warnings
For MS-DOS and Windows version 3.x: OtherServers=server1 [server2][ ...] |  | Access to LUs through servers outside a client's subdomain
For MS-DOS: OverrideDefaultLU={ YES | NO } |  | Default LUs as specified for PC Support instead of SNA Server
For MS-DOS: [SnaBase] LogonUserName=username | User name to use for logging on to servers; useful only for clients not running Microsoft Networking
For Windows version 3.x: BackupRemote= \\server1 [\\server2][ ...] or BackupRemote= subdomain | Sponsor connections (via alternate subdomain or sponsor servers) if the client software cannot connect to the primary subdomain or sponsor servers

Note Note that for clients running Windows version 3.x or MS-DOS but not running Microsoft Networking, command-line options can also be used to specify the user name and password when starting the SnaBase on the client. For more information, see "Variables for Clients Not Running Microsoft Networking," later in this chapter.

Table 8.4 lists the environment variable that can be set on a Windows-based client running the 3270 Applet.

Table 8.4 Environment Variable for a Windows-Based Client Running the 3270 Applet

Section and variable for WIN.INI file

What is affected

[SnaServerWin3270]
RetryConns={ yes | no }

Retrying when activation of a connection does not initially succeed and the cause of the problem may be temporary


Registry Variables Used Only on SNA Server

The Registry variables in the following sections can be set on a server only. To access or modify these variables, use the Registry Editor, REGEDT32. For information about the Registry Editor, see your Windows NT documentation.


SnaServer Service: SNA Servers of Variables

The Registry variables in this section affect the SnaServer service. They are all located in the same place in the Registry:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaServr
Parameters

The variables that affect the SnaServer service are as follows:

ALLOCINACT:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), the node will allocate pooled LUs even if they are inactive LUs on a connection that was activated on server startup or by an administrator. If this variable is not explicitly defined, only active LUs are allocated among pooled LUs on such a connection.

Setting this variable means that when users cannot get host access, they can use the OIA status line (in a 3270 emulator) to distinguish between two possible causes: all LUs are in use, or the host connection is down.

ALLOWBBRQE:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), the node allows Begin Bracket, Exception Response (BB RQE) on any request, even on requests that do not contain End Bracket (EB). If this variable is not explicitly defined, requests containing BB RQE but not EB are rejected with sense code 2003, in accordance with SNA protocols.

Note that BB RQE is allowed if Change Direction (CD) is set.

BINDRETRY:REG_DWORD:number Default: 2

Sets the session retry time-out (in units of 5 seconds) for the server to retry BIND attempts for autoactivated sessions. Setting BINDRETRY to 0 prevents retries.

CLEANUP:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), the local LU deactivates sessions by directly sending UNBIND (cleanup). If this variable is not explicitly defined, when LU 6.2 sessions are deactivated, the two LUs exchange BIS requests before UNBIND is sent. Setting this variable is a workaround for a possible host problem in which the LU is erroneously marked inactive.

COMBUF:REG_DWORD:number

This variable sets the size of the buffer pool available to the SnaServer service, in 16K units. Change this variable only if you receive error messages indicating that there is a buffer shortage. With a large number of gateway LUs, it may be necessary to set COMBUF to as large a value as 0x7F.

DloadMatchTPOnly:REG_SZ:{ YES | NO } Default: NO

When this variable is set to YES, the comparison between a request for a transaction program (TP) and the list of available invokable TPs is carried out on the TP name only. Otherwise, the comparison is carried out using both the requested TP name and the requested partner LU alias. This variable affects the servers on which it is set, but does not affect other servers.

Invokable TPs can be configured, through a Registry or environment variable on the system where the TP is located, to use a specific LU alias. If the invokable TP is configured in this way, the setting of DloadMatchTPOnly will control whether the LU alias is used in comparisons against incoming requests. If the invokable TP is not configured to use a specific LU alias, then no matter to whichLU alias an incoming request is sent, there cannot be a mismatch (regardless of the setting of DloadMatchTPOnly); with such TPs, matching is only affected by the TP name.

For information about TPs, see the Microsoft SNA Server APPC Programmer's Guide or the Microsoft SNA Server CPI-C Programmer's Guide.

The default is NO, meaning that the comparison uses both TP name and LU alias (when the LU alias has been configured for the invokable TP).

DloadMatchLocalFirst:REG_SZ:{ YES | NO } Default: YES

When this variable is set to NO, the comparison between a request for a TP and the list of available invokable TPs is carried out without regard to the location of the TP. Otherwise, invokable TPs on the local server are considered first for a potential match. This variable affects the server on which it is set, but not other servers in the subdomain.

For information about TPs, see the Microsoft SNA Server APPC Programmer's Guide or the Microsoft SNA Server CPI-C Programmer's Guide.

The default is YES, meaning that invokable TPs on the local server are considered first for a potential match.

FNA_SUPPORT: REG_SZ <value>

SNA Server supports the "Fujitsu Network Architecture" (FNA) variant to IBM SNA. Support for this alternate protocol is enabled by adding this registry variable. The <value> can be set to anything the administrator chooses that will identify the protocol to the system.

HNA_SUPPORT REG_SZ <value>

SNA Server supports the "Hitachi Network Architecture" (HNA) variant to IBM SNA. Support for this alternate protocol is enabled by adding this registry variable. The <value> can be set to anything the administrator chooses that will identify the protocol to the system.

INITSLFRETRIES: REG_SZ: Default: 0

When automatically activating a dependent APPC session, SNA Server sends an INIT-SELF command to the host, requesting that the host send a BIND command to start the APPC session. This parameter specifies the number of time an INITSELF is retried if a negative response is received from the host computer.

INITSLFTICKS: REG_SZ: Default: 2

The parameter specifies the number of tick periods (about five seconds) between INITSELF retries.

NO400D: REG_SZ: {YES | NO} Default: YES

When a host application initiates an LU0 session with full duplex send/receive mode (by setting bit 0-1 to "00" in Byte 7 of the BIND message), this indicates that the Change Direction (CD) is not used on the session. The CD bit is only used on half-duplex sessions to indicate which end has direction to send on a session.

Some host applications may still set the CD bit on a full duplex session and this is a protocol violation. The Registry variable fixes the host application so SNA Server will ignore this message. When set to YES, SNA Server will ignore any messages received by the host computer on an LU0 full duplex session which has the CD bit set. However, the LUA (RUI or SLI) application running on SNA Server is still not allowed to set the CD bit when sending messages to the hosts on a full duplex LU0 session, since this is a protocol violation.

NO4004:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), it causes the server to ignore sense code 4004. In other words, it causes CEB (conditional end bracket) to be accepted when EC (end chain) is not set, and EB (end bracket) to be accepted when BC (begin chain) is not set. If this variable is not explicitly defined, there is a normal response to sense code 4004.

NOINITCNOS:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), SNA Server will perform CNOS negotiation for APPC LUs only when sessions are required. If this variable is not explicitly defined, SNA Server performs these negotiations when the connection is started.

Note that with autoactivated sessions, regardless of the NOINITCNOS setting, CNOS negotiation must always be performed when the connection is started.

Setting this variable speeds up the starting process for connections that have large numbers of LUs.

NONOTIFYRSP:REG_SZ:{ YES | NO } Default: NO

When this variable is set to YES, SNA Server ignores the lack of response to a Notify request sent by the SNA Server node. If a Notify response is subsequently received, SNA Server processes it normally.

When this variable is set to NO, dependent LU sessions may become unusable due to the lack of a Notify response.

NORETRY:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), the server does not retry a BIND request when the response to the BIND is an UNBIND cleanup request. This prevents repetitive BIND failures when routing LU 6.2 sessions through a host.

NOTERMSELF:REG_SZ:{ YES | NO } Default: NO

When this variable is defined (with any value), 3270 sessions are terminated directly by sending UNBIND (cleanup). If this variable is not explicitly defined, a TERM-SELF is sent to solicit UNBIND from host. Setting this variable is a workaround for host-based session monitors that mark the LU as inactive after the TERM-SELF sequence.

RENEGLIMITS:REG_SZ:{ YES | NO } Default: YES

When this variable is set to YES, SNA Server always performs CNOS renegotiation when three criteria hold: no active sessions exist, SNA Server has a nonzero session limit, and an application BIND fails (regardless of sense code). Otherwise, SNA Server performs CNOS renegotiation according to the setting of RETRYCNOS.

Note that when RENEGLIMITS is set to YES, it overrides any setting of RETRYCNOS.

For a discussion of the renegotiation procedure that SNA Server uses by default (when variables such as RENEGLIMITS are not set), see the description for the next variable, RETRYCNOS.

RETRYCNOS:REG_SZ:{ YES | NO } Default: YES

When this variable is set to NO, SNA Server will not automatically renegotiate LU 6.2 session limits when the partner, without giving notice, resets these limits. Otherwise, SNA Server renegotiates the session limits whenever they are reset. The following paragraphs provide an overview of the CNOS renegotiation process performed by SNA Server.

By default, SNA Server performs CNOS negotiation at the start of day (when the session limits are initially 0), in response to an application issuing a CNOS verb, or whenever session limits are reset. The resetting of session limits becomes apparent to SNA Server when no active sessions exist, SNA Server has a nonzero session limit, and an application BIND is rejected either by an UNBIND request or with a BIND negative response containing one of the following sense codes:

Sense 1 | Sense 2
0x0806 | 0x3426 (Resource Unknown)
0x0805 | xxxxxx (Session Limit Exceeded)
0x0801 | xxxxxx (Resource Not Available)

SNA Server does not automatically reset session limits after a connection failure; when the connection is reactivated, renegotiation may not be necessary, and does not always occur.

If an application BIND fails after a previously successful CNOS negotiation, the most likely reason is that the partner LU has reset its session limits (perhaps because of a connection failure or being stopped and restarted) without SNA Server being informed by a request to renegotiate the session limits. In this situation, SNA Server will receive a BIND rejection of the type previously described, and by default will perform CNOS renegotiation. This CNOS renegotiation will resolve the problem of having a remote application that is active when no sessions are active on the connection.

If the CNOS renegotiation fails, no further attempts are made to activate the session until the connection is restarted or the SNA Server application retries.

With SNA Server, renegotiation is activated by default, and can only be deactivated by setting this variable to NO. For a description of a variable that overrides the effects of RETRYCNOS, see RENEGLIMITS.

Setting this variable to NO is a workaround for problems when communicating with CICS and the AS/400®.

SESTIMEOUT:REG_SZ:number

This variable sets the number of 5-second timer ticks allowed before the node deactivates contention winner sessions that are no longer in use. If the variable is not set, 4 timer ticks of 5 seconds each are allowed, for a total of 20 seconds.

Unique5250Names:REG_SZ:{ YES | NO } Default: YES

When this variable is set to NO, SNA Server will not ensure that session IDs generated by 5250 emulators are unique. Otherwise, SNA Server will substitute a unique session ID if any 5250 emulator generates a duplicate ID.

When a 5250 user establishes a session with an AS/400, a unique device name is required. Unless an override is sent, the AS/400 will generate the name by taking the Local LU and appending a 2-byte session ID sent by the emulator. A session ID generated by an emulator is usually not unique, since the emulator does not have information about the session IDs used by other active emulators. Therefore, by default, SNA Server alters the session IDs as they are sent out to ensure uniqueness. This is the recommended behavior, but it can be disabled by setting this Registry variable to NO.


SnaBase Service: SNA Servers of Variables

The Registry variables that affect the SnaBase service on a computer running SNA Server are found in the following location in the Registry:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters

These are the variable names and descriptions:

BackupSponsors: REG_MULTI_SIZE: server names

This is a list of all the backup SNA Server computers in the subdomain.

ConfigFilePath:REG_SZ:pathname
Default: SnaRoot\SYSTEM\CONFIG\COM.CFG

Specifies the path for the location of the configuration file on the local server; therefore, it applies only to primary or backup servers. This variable may need to be set to an explicit string (for example, a string such as C:\SNA\SYSTEM\CONFIG\COM.CFG) in unusual situations where software interaction prevents normal local access to the configuration file.

IgnoreClientUpdates: REG_SZ: {YES|NO} Default: NO

If YES all of the service table updates from SNA Server clients are ignored.

ListenBacklog: REG_DWORD: Default: 32

This variable specifies the maximum size to which the queue that holds pending connections can grow. This value is used by both the SnaBase and SnaServer services; however, it can only be configured in the SnaBase Registry setting.

If a Windows NT TCP/IP Winsock server application (like SNA Server) is bombarded with multiple, simultaneous TCP/IP connection requests when the listen() backlog queue is full, it will begin rejecting requests by replying with a TCP/IP reset frame.

To locate the problem, run a network trace with a protocol analyzer, count the number of unacknowledged TCP SYN connection request frames before the server starts replying with the TCP Reset bit set (which tells the sending station that the frame was received but the server did not have the resources to process the connection request).

The actual network interaction may appear as a delayed or slow connection because the client should attempt the connection again after waiting for a timeout.

SNA Server has a default "listen backlog" of 32 that can be adjusted higher or lower by using the ListenBacklog Registry parameter. The ListenBacklog is normally sufficient when set to five. This parameter is not added during Setup, and must be added manually. This value should only be increased if a large number of clients are all attempting to open sessions to SNA Server at the same time over TCP/IP sockets. If this value is modified, both SnaServer and SnaBase will use the new value.

The maximum values for the backlog setting in Windows NT are as follows:

Windows NT Version | Backlog
3.51 | 100
4.0 (Server) | 200
4.0 (Workstation) | 5

MacVersion:REG_DWORD: Default: 210

SnaBase sends the SNA Server version number to Macintosh clients.

PermanentServers: REG_MULTI_SZ Default: NONE

This specifies the names and/or IP addresses of SNA Server computers to where SnaBase always sends the service table updates, even if the SNA Server computers are not in the configuration file.

PrimaryServer: REG_SZ: servername

SNA Server backup and member server computers locate the primary SNA Server computer by contacting its name or IP address directly. It uses the primary server name entered during Setup of the backup or member server. Either the server name or an IP address can be entered. If using an IP address, use the standard notation layout, such as 123.45.67.89.

SecureSponsor: REG_SZ: {YES|NO} Default: YES

SNA Server client and server software support the ability to encrypt client-server data for LU session data as configured in SNA Server Manager by the Use Client/Server Encryption checkbox in the User property page. In addition, the data flowing over the sponsor session can be encrypted by setting the SecureSponsor Registry parameter to YES. This parameter can also use the values {ON|OFF}. Regardless of the parameter used, they must be entered in uppercase letters. The setting applies to all sponsor connections supported by the SNA Server computer on which the Registry parameter is defined. This entry must be configured on the server. Configuration on the client is optional.

SnaBackupDomain: REG_SZ

This is the name of the backup SNA Server subdomain and is a client-only parameter.

STServiceName: REG_SZ Default: <local computer name>

This parameter specifies the SNA Server Banyan VINES service name. The value can be any ASCII string less than 16 characters long. The default is the local computer name.

SyncConfigFiles:REG_SZ:{ ON | OFF } Default: ON

When this variable is set to OFF, replication of the configuration file from the primary server to any backup servers is disabled. Otherwise, the configuration file will automatically be replicated from the primary server to any backup servers whenever the configuration file is changed and saved. Setting this variable to OFF does not offer any performance gains, so it is generally best not to set the variable; that is, it's best to allow the default behavior (replicating the configuration file).

TerminatelfNoSponsors: REG_DWORD: {0|1} Default: 1

This is a client-only parameter. If this parameter value is set to 0, a client SnaBase cannot initially connect to an SNA Server computer and the client will terminate. If this parameter value is set to 1, SnaBase will not terminate if it cannot open the initial sponsor connection.

WatchDogTimeout: REG_DWORD: decimal value in seconds

This parameter defaults to 60 seconds if it is not configured. Both SNA Server and clients send these SNA Server specific "keepalive" messages, so both sides must be adjusted to prevent timeouts over very slow connections.

This parameter is valid for SNA Server, Windows NT clients, and Windows 95 clients. Windows 3.x clients adjust this parameter in the WIN.INI file in the [WNAP] section. Edit the line WatchDogTimeOut= <seconds>.

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
SnaLm

SNALM is the transport DLL for Microsoft Networking. The variable name and description is:

BufferSize:REG_WORD: {0|1|2|3} Default: 1

This entry specifies the Microsoft Networking input/output buffer size.

0 = It minimizes the memory usage. The buffer size equals the maximum message size.

1 = This is a compromise between 0 and 2 values. The buffer size is twice the maximum message size. This is the default value.

2 = Maximum performance, the buffer size is for time the maximum message size.

3 = This values allowsWindows NT Server to decide on the buffer size.

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
SnaSpx

The variable name and description is:

FlipMacAddress:REG_SZ {YES|NO} Default:

This entry is used with SPX connections (the protocol used in Novell NetWare networks). If set to YES, SNANW.DLL will bit flip the IPX node (MAC) address before trying to open an SPX connection. If the connection fails, it retries with the original non-flipped address. This entry can only be set on client computers.

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
SnaTcp

BroadcastDisabled:REG_SZ {YES|NO} Default: YES

SnaBase broadcasts service table updates over IP. A service table is a server-to-server data structure that each server in the subdomain has to keep track of SNA Server resources. These include real-time status of connections, invokable TPs, and LU pools.

If this entry is set to NO, SnaBase will send both service table broadcasts and directed datagrams over IP. If this entry is set to yes, it will use the method available for the version of SNA Server (2.1x or 3.0) residing on the computer.

If the UseBroadcasts Registry entry is set to YES, the BroadcastDisabled entry is disabled.

KeepAlive: REG_SZ: { YES|NO } Default: YES

This parameter was created to disable TCP/IPs keepalives. By default, TCP/IP will send its own keepalives on an idle connection every two hours when an SNA Server connection is bound to TCP/IP. When this is set to YES, it disables the keepalive. The Registry entry is the same on SNA Server, Windows NT clients, and Windows 95 clients.

To disable the keepalive on a Windows 3.x client, edit the KeepAlive = {YES|NO} line of the [WNAP] section of the WIN.INI file.

For more information see the section on WatchDogTimeOut in the SnaBase parameters section.

Network: REG_DWORD Default: 0

This entry specifies the network IP address SnaBase sends to clients and other servers in the subdomain. The allowed values are 0 to <the number of adapters -1> (one less than the total number of adapters). By default, SnaBase advertises the IP address associated with adapter 0. If the default is changed, SnaBase will advertise the IP address associated with other adapters on the computer.

UseBroadcasts:REG_SZ {YES|NO} Default: NO

This enables SNA Server 2.1x service table broadcasts over IP. SNA Server 2.1x sends broadcasts, 3.0 sends directed datagrams. If the value is set to YES, the SnaBase will use broadcasts. If it is set to NO (the default), SnaBase will send directed datagrams.


SNA Server Management Architecture: SNA Servers of Variables

SNA Server Management Architecture:
SNA Servers of Variables

The variables that affect Manage Agent or Manage Client are found in the following Registry location:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
SnaServer
CurrentVersion
Manage

These are the variable names and descriptions:

ClientExt: REG_MULTI_SZ Client extension DLL names

This is a list of extension DLLs used by Manage Client. The DLLs are used by Manage Client to recognize manage data being sent by Manage Agent. If a DLL is removed from the Registry, Manager Client would not respond to the data, even if Manage Agent knows about it.

MaxDomains: REG_DWORD Default: 10

An optional value that limits the number of subdomains the client can manage. The default (and maximum number allowed) is 10; however, this number can be decreased depending on the need. The Registry is not created during Setup and must be manually added. It is only used by Manage Client.

MaxProcess: REG_DWORD Default: 64

This value can be increased or decreased to manage the number of client processes. The Registry is not created during Setup and must be manually added.

MaxServer: REG_DWORD Default: 150

This variable corresponds to the number of subdomains to which the client has access. For example, if the client is able to access 10 subdomains that have 15 SNA Server computers each, then they can access a maximum of 150 servers. This value can be decreased to manage the number of server computers the client can access. It is only used by Manage Client. The Registry is not created during Setup and must be manually added.

MaxTypes: REG_DWORD Default: 50

This variable allows the administrator to set the maximum number of manage object types supported. The value can be increased or decreased depending on the need. The Registry is not created during Setup and must be manually added.

ServerExt: REG_MULTI_SZ Server Extension DLL Names

This is a list of extension DLLs used by Manage Agent. The DLLs are a list of services that are defined and active in SNA Server. If one of the services in the string is removed, Manage Agent will not receive any management information from the service. An entry in the Registry also implies that the corresponding service has been added. For example, if Host Print Service was not installed, then the DLL should not be added on the SNA Server computer. However, it should still appear on the client computer (in ClientExt), as another server may have installed Host Print Service, and SNA Server Manager may need to display data from that server. In summary, ClientExt should have a DLL entry for all known services and ServerExt should only have an entry for those services that reside on the same machine.

If a service is added using the Registry, then it must be added to both the client and server entries. Also, any additions require changes to SNA Server Manager, so the client can see it. Therefore, it is recommended that any service additions be made using SNA Server Manager or Setup.


SNA Server Remote Access Service: SNA Server of Variable

SNA Server Remote Access Service:
SNA Server of Variable

The Registry variables that affect the SNA Remote Access Service on a computer running SNA Server are found in the following location in the Registry:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
RAS
OTHER DEVICES
INSTALLED
SnaRas

There is one user-configurable variable:

NumberOfDevices:REG_DWORD:ports Default: 10

Specifies the number of RAS devices (ports) that can be configured for SNA Remote Access Service.


SNA Server Shared Folders Gateway Service: SNA Servers of Variables

SNA Server Shared Folders Gateway Service:
SNA Servers of Variables

The variables that affect the Shared Folders Gateway service are found in the following Registry location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SFGW
Parameters

AllocateTimeout: REG_DWORD: Default: INFINITE

This specifies the number of seconds the Shared Folders Gateway waits for an ALLOCATE verb to complete before reporting an error. Other values are 1 to 4294966 seconds.

By default, the Shared Folders Gateway will wait forever for the ALLOCATE verb to complete. If the value is changed, the Shared Folders Gateway will cancel the ALLOCATE verb if it does not complete in the configured time and will also report an error.

AnsiPage: REG_DWORD: Default: 0

This specifies the ANSI code page used in the EBCDIC/ASCII conversion.

ContextCacheSize: REG_SZ: Default: FolderCacheSize + FileCacheSize

This parameter configures the size of the Shared Folders Gateway file/folder context cache size. A context is a data structure that holds the state, such as current file offset, of an open file/folder.

EbcdicPage: REG_DWORD: Default: 37

This specifies the EBCDIC code page used in the EBCDIC/ASCII conversion.

FileCacheSize: REG_SZ: Default: 16

FileCache is a cache that stores currently unused FileObjects. This enhances performance as it is faster to allocate and release FileObjects to and from the cache rather than create a new object and then delete it. The maximum value for this parameter is 256.

FoldersCacheSize: REG_SZ: Default: 16

This is the internal folder cache size. The FolderCache parameter stores unused FolderObjects in the cache in the same manner as FileCacheSize. The maximum value is 256.

ForceUpperCase: REG_SZ: Default: YES

If YES, the Shared Folders Gateway converts user names and passwords to upper case before sending them to the AS/400.

MaxConversations:REG_DWORD: Default: 8

This specifies the maximum number of conversations per AS/400 that the Shared Folders Gateway allocates. The minimum number of conversations allowed is one, the maximum is 64.

MaxWorkBuffers: REG_SZ: Default: 32

This specifies the maximum number of work buffers allowed. These buffers are used to pass data between the shared folders file system driver and the gateway service itself.

MaxWorkThreads: REG_DWORD: Default: 4

This specifies the maximum number of worker threads per processor. The maximum value for this is 64. Worker threads process file system requests such as open file, read file, write file, close file and many others.

Mode:REG_SZ: Default: QPCSUPP

This specifies the APPC mode name. For more information about modes see "What are Modes and How Do I Use Them?" in Part 4 of the Microsoft SNA Server Administration Guide.

RemoteTPName:REG_BINARY: Default: 0x30 0xF0, 0xF4 0xF6

This specifies the partner TP name.

TPName:REG_SZ: Default: SFGW

This specifies the local Shared Folders Gateway TP name. It can be any ASCII string of eight characters. The default is SFGW.

UnloadDriver:REG_DWORD Default: 1

This will unload the shared folders files system driver (SFFSD.SYS) when the Shared Folders Gateway service terminates. If it is set to 0, it will not unload.


SNA Server TN3270 Service: SNA Servers of Variables

The variables that affect the TN3270 service are found in the following Registry location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
TN3270
Parameters

These are the variable names and descriptions:

AuditEvents: REG_EXPAND_SZ {ON|OFF} Default: OFF

This registry entry controls whether audit events are written to the event log. The default is off, preventing logging of audit events. If it is turned on, the audit events will be written to the event log.

ConnectionTimout: REG_DWORD

The TN3270 service monitors active and idle times. If the service has been idle for a specified number of minutes, it will issue a connection time out and close the connection.

DefaultInboundRUSize: REG_DWORD

This is the specification for the RU size for inbound (TN3270 client to host) SSCP data.

DefaultOutboundRU Size: REG_DWORD

This is the specification for the outbound RU size (host to TN3270 client) SSCP data.

CloseListenSocket: REG_EXPAND_SZ {ON|OFF} Default: OFF

The TN3270 service monitors its port for available LUs. If this entry is turned on, the service stops monitoring the port when all of the configured LUs are in use. It resumes monitoring when an LU becomes available.

NoTN3270E: REG_EXPAND_SZ {ON|OFF} Default: OFF

Part of TN3270 service is the incorporation of TN3270E protocols. If this Registry entry is set to on, the TN3270 service does not use the TN3270E protocols. This is helpful because some TN3270 clients cannot negotiate successfully with a TN3270E server and the system will stop responding. This Registry entry disables the TN3270E protocols allowing the client successful negotiation.

GetClientHostName: REG_EXPAND_SZ {ON|OFF} Default: OFF

When this is set to on, TN3270 service translates the client IP address to the resolved name before passing the client status information to SNA Server Manager.

InitStatusDelay: REG_DWORD

This specifies the number of seconds during which the TN3270 service does not send status messages to the client during startup. It prevents a influx of messages at the client during startup.

LogToSNAEventLog: REG_EXPAND_SZ {ON|OFF} Default: OFF

If this is set to on, the TN3270 service logs its events on the same machine as the SNA Server computer in the subdomain. If this is set to off, it logs events to the local machine.

MessageCloseDelay: REG_DWORD

When the TN3270 service forces a client disconnect, it sends a message to the client. This option specifies the number of seconds TN3270 service keeps the connection active after sending the termination message. This message appears to inform the user of the disconnection because some client computer screens are cleared once they are disconnected from the server.

ReplaceRUSize: REG_EXPAND_SZ:{ON|OFF} Default:

TN3270E printer sessions will hang if the host computer sends a BIND RU that specifies an Inbound Maximum RU size of 0, which indicates that maximum RU size does not apply on the session. This causes the print job to remain in "Spooling…" state in the Windows NT Print Manager until the printer session is disconnected.

The administrator needs to ensure that the TN3270 service sends inbound data. The data is sent in Request Units (RUs) up to the Default Inbound Size specified in the Options dialog box of the TN3270 administrator.

The TN3270 service also has a Registry entry that allows a 0 RU size in the BIND image transmitted to the client to be overwritten by the Default Inbound RU Size specified in the Options dialog box. If this entry is set to ON, then the value for the inbound RU size is set to the specified Default Inbound RU Size if the host has not specified a maximum size.


SNA Server Host Security: SNA Servers of Variables

The Registry variables in this section affect Host Security Integration and are located in the following areas:

Windows NT Account Synchronization Setup

There are two password change variables in the Registry. The first is found in the following location:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
SnaServer
CurrentVersion
Host Security
Password Change

The variable that affects this Registry entry is as follows:

MdbDomain:REG_MULTI_SZ Windows NT Domain Name

This Registry entry contains the name of the Windows NT domain names entered in the Domains Providing dialog box in Setup. Additional Windows NT domain name can be added using this registry setting and can be an unlimited number.

The second Registry entry is in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Control
Lsa

The variable that affects this Registry entry is as follows:

NotificationPackages: REG_MULTI_SZ path name

This is the complete path for the SNA Server password change. It is entered without the DLL extension. For example, the path d:\sna\system\snapwchg is a valid path name.

Password Management Process (PMP)

The Registry variables that affect PMP are in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SNAPMP
Parameters

The variables that affect PMP are as follows:

RolePrimary: REG_DWORD {1 | 0}

For the primary process management process (PMP), the value is 1. For all other PMPs the value is 0.

MdbDomains:REG_MULTI_SZ

This Registry entry contains the name of the Windows NT domain names entered in the Domains Providing dialog box in Setup. An unlimited number of additional Windows NT domain names can be added using this registry setting.

Host Account Synchronization Process

The Registry variables that affect the Host Account Synchronization are in two locations. The first is:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SNAHostProcess
Parameters

The variables that affect Host Account Synchronization are as follows:

InitializeInterval: REG_DWORD Default: 60 seconds

This value represents the decimal number of seconds to reissue the RpcServerInitialize call.

The second Registry entry location is:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SNAHostProcess subkeys

The subkeys that affect Host Account Synchronization are as follows:

Domains

For each host security domain defined, there is a subkey under the Domains subkey that contains the values needed by the security integration DLL.

Security DLLs

This is the root of template information for registered security integration DLLs. The Host Security Wizard in SNA Server Manager uses this information to create host security domain definitions under the Domains subkey. For each security integration DLL supported by the wizard, there is a subkey whose name is the security integration DLL The wizard copies any values it finds under this subkey to the Domains subkey. The wizard then replaces the "placeholder" in the values with the actual names of SNA resources it collects from the user dialog and substitutes the actual strings into the Registry values constructed in the Domains subkey. The current placeholder values are:

  • %F - The file name of the third-party DLL.
  • %L - The local APPC LU.
  • %R - The remote APPC LU.
Host Security Domain Definitions for Security Integration DLLs

The security integration DLLs are in the following Registry location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SNAHostProcess
Parameters
Domains
domainName

The Host Account Synchronization process requires a single value under this subkey as follows:

HostSecurityDLL:REG_SZ Default: %F

This is the file path to security integration DLLs. It is used by the host process to load the DLL during initialization.

The remaining variables are used only by the specific security integration DLL which varies from vendor to vendor. The variables used by SEC400.DLL, which is bundled with SNA Server, are as follows:

ForcetoUpper:REG_SZ: Default: True

When this is set to true, it causes the SEC400.DLL to force lowercase usernames and passwords when converting from Windows NT to AS/400. It forces uppercase to lowercase when converting from the AS/400 to Windows NT.

LocalLU:REG_SZ Default: %L

This identifies the local APPC LU used to communicate with the host computer.

RemoteLU:REG_SZ Default: %R

This identifies the remote APPC LU used to communicate with the host computer.

TPMode:REQ_SZ Default: QPCSUPP

The mode determines the type of session established in an APPC session. This entry determines whether the session is batch, interactive, on an AS/400, or to be used with the ODBC drivers. The default is QPCSUPP, which is used for all sessions with an AS/400 computer.

For more information about modes and how to use them, see the topic "What are Modes and How Do I Use Them" in Part 4, "SNA Server APPC Connectivity," in the Microsoft SNA Server Administration Guide.

Host Account Cache

The Registry variables that affect the Host Account Cache are in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaDatabase
Parameters

The variables that affect the Host Account Cache are:

Master:REG_DWORD Default: 1

If the Host Account Cache resides on the primary controller, it is the master copy, or a default of 1. If it is on a backup or member server, the entry is 0.

DatabaseFile:REG_EXPAND_SZ path name

The full path to the master data base is used. For example, the default path could be <snaroot>\CONFIG\Dbase.DBS.


Registry Entries for Link Services

The following lists the Registry variables for SNA Server link services.


Transport Protocols

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaLink
Parameters

The Registry variables that affect the network transport protocols of TCP/IP, IPX/SPX, and Banyan VINES are:

IpPort: REG_DWORD Default: 0

IpxPort:REG_DWORD Default: 0

VinesPort:REG_DWORD Default: 0

These Registry variables specify the TCP/IP (IpPort), IPX/SPX (IpxPort), and Banyan VINES (VinesPort) port number the remote link services listen to for incoming connections. If the value is 0 the transport DLL allocates a dynamic port. This means that the port number will be different every time the service is restarted. The other value is any valid Banyan VINES IP port number between 0x200 and 0xFFFE.

The valid values for IpPort are from 1 to 0xFFFE. Values below 0x800 are not recommended. Values 0x5C5 and 0x5C6 are reserved for SNA Server and cannot be used.

The valid values for IpxPort are from 1 to 0xFFFE. The values 0x84C8 and 0x84C9 are reserved for SNA Server and cannot be used.


Distributed Link Service

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaRemX
Parameters

The following Registry variables affect the SNA Server Distributed Link Service.

LocalIpPort:REG_DWORD: Default: 0

LocalIpxPort:REG_DWORD: Default: 0

LocalVinesPort: REG_DWORD: Default: 0

These Registry variables specify the port number the distributed link service uses to connect to the remote computer. If set to 0, it will use dynamic ports.


DLC (802.2) Link Service: SNA Server of Variable

The Registry variable that affects the DLC (802.2) link service is found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
DLCLinkServiceName
Parameters
ExtraParameters

This is the variable name and description:

FrameType:REG_DWORD:number

This variable specifies the type of frames for the DLC (802.2) link service to send over an Ethernet LAN. The variable need be set only if the LAN is Ethernet, not token ring, and only if the server communicates with remote host, peer, or downstream systems via routers (not MAC layer bridges).

If the server communicates over Ethernet via routers, check with the local network support staff to determine what type of frames the routers pass. The frames can be either standard 802.3 format or 802.2 packets prefixed by DIX headers using EtherType value 0x80D5.

Specify the number in FrameType as follows:

Value | Effect
0 | Use the frame type specified for this adapter in the Registry entry for the DLC protocol stack: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services \DLC\Parameters\AdapterName\UseDixOverEthernet. The default for UseDixOverEthernet is 0, resulting in 802.3 format.
1 | Use the frame type automatically determined by the DLC stack during XID exchange.
2 | Use standard 802.3 format.
3 | Use 802.2 packets prefixed by DIX headers using EtherType value 0x80D5.

If FrameType is not set, it defaults to 0, which means that the frame type is the one specified in UseDixOverEthernet, as described in the preceding table.


X.25 Link Service: SNA Server of Variable

The Registry variable that affects the X.25 link service is found in the following location in the Registry:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
X.25LinkServiceName
Parameters
ExtraParameters

This is the variable name and description:

ACCPTFMT:REG_SZ:{ 0 | 1 } Default: 0

When this variable is set to 1, calling and called addresses are omitted on a CALL_ACCEPT packet that is sent in response to an incoming call. Setting this variable to 1 is a workaround for a problem when the host rejects standard X.25 CALL_ACCEPT packets.


Registry Variables Used on SNA Server, a Windows NT Client, or a Windows 95 Client

The Registry variables in the following sections can be set on SNA Server or on a Windows NT client. MaxThreads can be set only on a Windows NT client, and SnaBackupDomain and BackupSponsors can only be set on Windows 95 and Windows NT clients. To access or modify these variables, use the Registry Editor, REGEDT32 (Windows NT) or REGEDIT (Windows 95).

Note The following sections do not include the variables used for configuring an invokable TP. For information about these variables, see Chapter 2 of the Microsoft SNA Server APPC Programmer's Guide or Chapter 2 of the Microsoft SNA Server CPI-C Programmer's Guide.


APPC API: SNA Server of Variable

For SNA Server or a Windows NT client, the Registry variable that affects the APPC API is found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
Client

This is the variable name and description:

LUWIDSUP:REG_SZ:{ YES | NO } Default: YES

When this variable is set to NO, support is deactivated for the logical unit of work identifier (luw_id). Normally, this support is used in APPC, but Comm Server 1.x did not support it. Setting this variable to NO allows compatibility with Comm Server 1.x software.


CPI-C API: SNA Servers of Variables

For SNA Server or a Windows NT-based client, the Registry variables that affect the CPI-C API are found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
Client

These are the variable names and descriptions:

application:REG_SZ:localLUalias

For this variable, substitute the name of the application for application, and the local LU alias for localLUalias. This variable specifies the local LU alias to be used with a CPI-C application that invokes another application. For information about TPs and APPC LUs, see the Microsoft SNA Server Administration Guide.

APPCTPN:REG_SZ:TPname

For this variable, substitute the name of the local TP, in ASCII, for TPname. For information about TPs and APPC LUs, see the Microsoft SNA Server Administration Guide.


CSV API: SNA Servers of Variables

For SNA Server or a Windows NT-based client, the Registry variables that affect the CSV API are found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
Client

These are the variable names and descriptions:

COMTBLG:REG_SZ:filename

This variable specifies the name of the file that contains Table G for code conversion. Table G is used with the CONVERT verb.

For more information about CSV, see the Microsoft SNA Server APPC Programmer's Guide.

COMCPT:REG_SZ:path

This variable specifies the directory in which the code page file (for code conversion) is located. For example, if the code page file is located in the directory C:\PAGEDIR, the setting to use is as follows:

COMCPT:REG_SZ:C:\PAGEDIR

For more information about code pages, see the Microsoft SNA Server APPC Programmer's Guide.


LUA API: SNA Server of Variable

For SNA Server or a Windows NT client, the Registry variable that affects the conventional Logical Unit Application programming interface (LUA) API is found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters
Client

This is the variable name and description:

SNAMAXLUALUS:REG_DWORD:number

This variable sets the maximum number of frames in the protocol window. Setting this number lower means that fewer buffers will be required on the system. It is unlikely that this variable would be required for a Windows NT-based system.


SnaBase: SNA Servers of Variables

For SNA Server or a Windows NT-based client, the Registry variables that affect the SnaBase are found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters

These are the variable names and descriptions:

BufferAuditInterval:REG_DWORD:number

This variable causes SNA Server computers and client computers to carry out audits of the buffer pool at regular intervals, and sets the interval length in seconds. (SNA Server rounds the number of seconds upward to the nearest 5 seconds.) The range for number is 1 through 0xFFFFFFFE. The parameter must be configured individually on server and client computers.

Normally (that is, when this variable is not set), SNA Server only carries out buffer audits when a buffer pool is extended and more than half of the buffer pool is in use.

When SNA Server carries out a buffer audit, the information is placed in message 684 in the application event log.

LOCALLUS:REG_MULTI_SZ:localLUname

This entry is no longer used in SNA Server 3.0.

OtherServers:REG_MULTI_SZ:server1 [server2][ ...]

This variable specifies one or more servers outside of the client's subdomain to which the client's requests for LUs will be sent if the requests cannot be satisfied by servers in the client's subdomain. If this variable is not set, only servers in the client's subdomain will receive the client's requests for LUs.

When specifying the variable, substitute one or more server names for
server1 [server2][ ...]. Separate multiple server names with spaces.

COMPOP12:REG_SZ:{ YES | NO } Default: NO

When this variable is set to YES, level 12 warnings do not display as pop-up messages on the local system. (Level 12 messages are not as severe as level 16 messages.)

SnaBackupDomain:REG_SZ:domain

This variable specifies a backup subdomain for a client configured to run in local mode. When the client software is starting, if it cannot connect to its primary sponsor subdomain, the client software will attempt to connect to the backup subdomain.

BackupSponsors:REG_MULTI_SZ: server1 [server2][ ...]

This variable specifies one or more backup sponsor servers for a client configured to run in remote mode. When the client software is starting, if it cannot connect to its primary sponsor servers, the client software will attempt to connect to the backup sponsor servers. If the SnaBackupDomain variable is present, the BackupSponsors variable is ignored.

When specifying the variable, substitute one or more server names for
server1 [server2][ ...]. Separate multiple server names with spaces.

Note that this variable is of type REG_SZ in the Windows 95 Registry.


Lan Manager Workstation: SNA Server of Variable

If you have an application written to one of the SNA APIs offered by SNA Server (such as APPC, CPI-C or LUA) on Windows NT clients using Microsoft Networking, and your application uses a large number of Windows NT threads, you may need to add a Registry variable on the clients to permit correct operation.

This Registry variable is called MaxThreads. It can be set on a Windows NT-based client and is found in the following location:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
LanmanWorkstation
Parameters

This is the variable name and description:

MaxThreads:REG_DWORD:number

This variable specifies the number of threads available for use by the Workstation service. Set number to a value between 30 and 255, depending on how heavily the workstation is used by APPC. Try to make the value large enough to support all the APPC usage, but low enough to avoid using excessive amounts of memory.

If this variable is not set, it defaults to 6 threads.


Adding Server Names to Windows NT, Windows 95, and Windows 3.x Clients

When running Setup for clients, the program prompts for two remote server names. You can add additional remote server names using the Registry (for Windows NT and Windows 95 clients) or by modifying the WIN.INI file (for Windows 3.x clients).

Windows NT Client

On a Windows NT client, you can add server names to the following Registry variable:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
SnaBase
Parameters

Sponsors: REG_MULTI_SZ: server1 server2 server3

Enter the server names with a space between each name. The only limit to the number of servers that can be added is the number of servers in the subdomain.

Windows 95 Client

On a Windows 95 client, you can add server names to the following Registry variable:

HKEY_LOCAL_MACHINE
SOFTWARE
Microsoft
SnaBase
Parameters: Sponsors: server 1 server2 server3

Enter the server names with a space between each name. The only limit to the number of servers that can be added is the number of servers in the subdomain.

Windows 3.x Clients

Add server names (preceded by "\\") on the Remote= line in the WNAP section of the WIN.INI, separating the server names with spaces. When connecting over TCP/IP, the server's IP address may be can be specified:

Remote= \\server1 \\server2 \\124.55.69.45


RandomSponsor Setting

SNA Server allows clients to randomly choose a sponsor server. This provides load balancing across SNA Server computers to evenly distribute the available resources.

This setting can only be configured in the Registry for Windows NT clients and in the WIN.INI file for Windows 3.x and Windows for Workgroups clients. The RandomSponsor is not configurable for the Windows 95 client as remote sponsor servers are always tried in random order.

The RandomSponsor setting is enabled by default for Windows 3.x and Windows NT clients. It can be disabled using the Registry and WIN.INI files.

Windows NT Clients

To disable the RandomSponsor setting for Windows NT clients, use the following Registry entry:

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
SnaBase
Parameters

RandomSponsor:REG_DWORD:0

After the Registry is modified, the client SnaBase service must be restarted. If the RandomSponsor setting is disabled, the client will try the remote servers in the order of configuration.

Windows 3.x or Windows for Workgroups Clients

In the WNAP section of the WIN.INI file modify the RandomSponsor line:

RandomSponsor=NO


Environment Variables Used on Clients Running Windows Version 3.x, MS-DOS, or OS/2

Environment Variables Used on Clients Running
Windows Version 3.x, MS-DOS, or OS/2

The environment variables in the following sections can be set on an SNA Server client running the Windows version 3.x, MS-DOS, or OS/2 operating systems. For information about accessing or modifying these variables, see "Setting Variables on Different Operating Systems" earlier in this appendix.

Note The following sections do not include the variables used for configuring an invokable TP. For information about those variables, see Chapter 2 of the Microsoft SNA Server APPC Programmer's Guide or Chapter 2 of the Microsoft SNA Server CPI-C Programmer's Guide.


APPC API

LUWIDSUP={ YES | NO } Default: YES

When this variable is set to NO, support is deactivated for the logical unit of work identifier (luw_id). Normally, this support is used in APPC, but Comm Server 1.x did not support it. Setting this variable to NO allows compatibility with Comm Server 1.x software.


CPI-C API

[ApplicationName]
APPCLLU=localLUalias

For this variable, substitute the name of the application for ApplicationName, and the local LU alias for localLUalias. Type the square brackets around the application name, and place the application name on a separate line, as shown. This variable specifies the local LU alias to be used with a CPI-C application (a TP).

APPCTPN=TPname

For this variable, substitute the name of the TP, in ASCII, for TPname. This variable specifies the local TP name.


CSV API

COMTBLG=filename

This variable specifies the name of the file that contains Table G for code conversion. Table G is used with the CONVERT verb.

For more information about CSV, see the Microsoft SNA Server APPC Programmer's Guide.

COMCPT=path

This variable specifies the directory in which the code page file (for code conversion) is located. For example, if the code page file is located in the directory C:\PAGEDIR, the setting to use is as follows:

COMCPT=C:\PAGEDIR

For more information about code pages, see the Microsoft SNA Server APPC Programmer's Guide.


LUA API

SNAMAXLUALUS=number

This variable sets the maximum number of frames in the protocol window. Setting this number lower means that fewer buffers will be required on the local system. This is particularly important with MS-DOS, where buffer availability is limited. The credit values are based on two LUs per application.


SnaBase

These are the variable names and descriptions:

For Windows version 3.x:

AutoTerminate={YES | NO} Default: NO

When this variable is set to YES, wnap is automatically closed when the Windows 3.x application session is closed. Wnap must be automatically started for the automatic termination to be enabled. If wnap is manually started, wnap will not terminate, even if set to Yes.

For MS-DOS and Windows version 3.x:

LOCALLUS=localLUname, localLUname[, ...]

This entry is no longer used in SNA Server 3.0.

OtherServers=server1 [server2][ ...]

This variable specifies one or more servers outside of the client's subdomain, to which the client's requests for LUs will be sent, if the requests cannot be satisfied by servers in the client's subdomain. If this variable is not set, only servers in the client's subdomain will receive the client's requests for LUs.

When specifying the variable, substitute one or more server names for
server1 [server2][ ...]. Separate multiple server names with spaces.

This entry is no longer used in SNA Server 3.0.

BackupSponsors=\\server1 [\\server2][ ...] or BackupSponsors=subdomain

This variable specifies a backup subdomain for a client configured to run in local mode or backup sponsor servers for a client configured to run in remote mode. If the client software cannot connect to its primary sponsor subdomain or sponsor servers when it is starting, it will attempt to connect to the backup subdomain or servers. If the string supplied as the value of the variable begins with a double backslash (\\), it is expected to be one or more server names; otherwise, it is treated as a subdomain name.

For OS/2:

COMLUASS={ YES | NO } Default: NO

When this variable is set to YES, LUs on this system are assigned on a per-workstation basis, using the LAN computer name. Otherwise, SNA Server attempts to assign LUs on a per-user basis, using the currently logged-on LAN user identification.

For MS-DOS, Windows version 3.x, and OS/2:

COMPOP12={ YES | NO } Default: NO

When this variable is set to YES, level 12 warnings do not display as pop-up messages on the local system. (Level 12 messages are not as severe as level 16 messages.)

For MS-DOS:

OverrideDefaultLU={ YES | NO } Default: NO

When this variable is set to YES, SNA Server will use the default APPC LUs configured for PC Support; these LUs are specified on the RTLN line of the CONFIG.PCS file. Otherwise, SNA Server will use the default APPC LUs configured in SNA Server; these LUs are assigned to users or groups through SNA Server Manager or through the SNA Server command-line interface (snacfg).

For more information about PC Support, see the following sections in Chapter 3 of the Microsoft SNA Server Getting Started:

  • "PC Support Used with Windows for Workgroups"
  • "Installing an MS-DOS – Based Client," which includes the subsection "PC Support Router Replacement."


Variables for Clients Not Running Microsoft Networking

The information in this section affects the logon process for clients running Windows version 3.x but not running Microsoft Networking. With these clients, two logons must take place: one for access to the Windows NT domain and one for access to the servers in the domain.

For Clients Running Windows version 3.x

For clients running Windows version 3.x but not running Microsoft Networking, users' names are stored each time they log on for access to servers. At the time of the next logon for access to servers, a user's name is offered in the logon dialog box. (Password information is not stored.)

Also, for clients running Windows version 3.x but not running Microsoft Networking, command-line options can be used to specify the user name and password when starting the SnaBase (which is called wnap in the Windows 3.x environment). The syntax for this is:

wnap /user:username /pwd:password

An example of a client for whom the preceding command might be appropriate is a client running Windows version 3.x with Novell® NetWare®.

A user who does not use a password may want to type the preceding syntax without typing any characters after /pwd:. This will suppress the dialog box that requests a password.

If the preceding syntax line is used on a client running Microsoft LAN Manager (which is a Microsoft network software product), the user and pwd options are ignored, since the only logon needed for clients using Microsoft Networking is the logon in the Windows NT domain (that is, no additional logon is needed to access the servers in the domain).

For Clients Running MS-DOS

For clients running MS-DOS but not running Microsoft Networking, the following section and line can be placed in the SNA.INI file to simplify the process of starting up the SnaBase and logging on to the servers in the Windows NT domain. When typing the section name, include the square brackets.

[SnaBase]
LogonUserName=username

Note that for clients running MS-DOS but not running Microsoft Networking, command-line options can also be used to specify the user name and password when starting the SnaBase on the client. The syntax for this is:

snabase /user:username /pwd:password

An example of a client for whom the preceding command might be appropriate is an MS-DOS – based client running Novell NetWare.

A user who does not use a password may want to type the preceding syntax without typing any characters after /pwd:. This will suppress the dialog box that requests a password.

If the preceding syntax line is used on a client running Microsoft LAN Manager (which is a Microsoft network software product), the user and pwd options are ignored, since the only logon needed for clients using Microsoft Networking is the logon in the Windows NT domain (that is, no additional logon is needed to access the servers in the domain).


Variable for Windows-Based Clients Running the 3270 Applet

The variable in this section applies only to clients running the 3270 Applet with Windows NT or Windows version 3.x. On either type of client, the variable is set in the WIN.INI file. This is true even for Windows NT-based clients; the WIN.INI file for such clients belongs in the operating-system root directory.

The variable is set in the WIN.INI file by adding a section called [SnaServerWin3270] to the file and adding a line with the following syntax to that section:

RetryConns={ yes | no } Default: no

If set to yes, causes the 3270 Applet to retry unsuccessful connection attempts in certain circumstances where the condition causing the problem is probably temporary (see the next paragraph). Otherwise, the 3270 Applet does not retry unsuccessful connection attempts; instead, the user can retry manually by disconnecting and connecting again.

Conditions that are considered temporary are:

  • All LUs in the requested pool are in use at that moment (code 0x0057).
  • The requested LU pool is not found in the configuration, which may indicate that the server through which the client is attempting to connect is inactive (code 0x0A0E).
  • The requested connection is inactive at that moment (code 0x1002).
  • The host (or controller unit) has not yet responded with an ACTPU command (code 0x1010).
  • The host (or controller unit) has not yet responded with an ACTLU command (code 0x1011).


Important Information Regarding IBM PS/2

In certain circumstances, when a connection is activated using SDLC or X.25 on an IBM PS/2 computer configured with an IBM MPA/A (or the MicroGate equivalent), the computer freezes and fails to respond to keyboard or mouse input.

There are two problems that cause this problem to occur:

  • The IBM PS/2 abios disk controller tries to allocate all available map registers for large data transfers. The standard SDLC drive allocates two when the SDLC connection is activated and never releases them. The disk controller hangs while waiting for the map registers. The entire system will slowly hang as paging and disk access are stopped.
  • The IBM PS/2 abios disk controller performs DMA data transfers at the interrupt processor level. Windows NT defines this as an illegal operation. The SDLC driver allocates a DMA resource, then the disk controller generates an interrupt, and tries to acquire the DMA resource. It cannot acquire it and will never be able to as the disk controller has locked out the driver that owns it. The system is locked.

Both problems are solved by applying the alternate IBMSYNC.SYS driver. If the default IBMSYNC.SYS driver is used, the first problem is solved through the support of a special Registry parameter for the IBMSYNC driver.

A special version of the IBMSYNC.SYS driver is located on the SNA Server 2.11 CD-ROM. To install the driver, see the Release Notes (README.WRI) on the CD-ROM.

Using the default IBMSYNC.SYS driver, the following Registry parameter prevents the driver from requesting mapped registers. This version of the driver does not correct the other problem observed on IBM PS/2 computers.

HKEY_LOCAL_MACHINE
SYSTEM
CurrentControlSet
Services
IBMSYNC
Parameters

DontUseMapRegisters: REG_DWORD: Default: 1

After configuring this option, restart SNA Server.


Chapter 9 Event Viewer Messages

This chapter lists the messages that are logged in the event log for SNA Server.


Message 1

(value) Protocol Violation

EXPLANATION: A remote node generated an SNA protocol violation on an SNA network. The remote system may have a configuration or internal logic error.

SUBCODE INFORMATION:

X'1120' The node received an SNA message that contains only a Transmission Header (TH). No request header or request unit is present.

X'1121' The node received an SNA message with an invalid TH.

X'1122' Segmentation error: the first segment of a received SNA message did not contain a Request Header (RH).

X'1131' The node received a Network Control request. This is an invalid request category; Network Control requests are not supported.

X'1134' The node received an SNA message containing an unsupported Session Control request.

X'1135' The node received an SNA message containing an unsupported Session Control response.

X'1175' The node received an SNA message containing an unsupported Change Number of Sessions (CNOS) request.

X'1185' The node received an SNA message containing an unsupported network management request or subvector.

X'118D' The node received an SNA message containing an error in BIND request unit from partner LU.

X'11D0' The node received an error in an LU 6.2 SNA request message from a partner LU. A SEND indication (CD) was expected but not received by the node.

X'11D1' The node received an error in an LU 6.2 SNA error data GDS variable from a partner LU.

X'11D2' The node received an error in an LU 6.2 SNA message from a partner LU (unexpected reporting of mapping error).

X'11D3' The node received an error in an LU 6.2 message from a partner LU (an invalid return code was generated from an FMH-7).

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 2

(value) Internal Error

EXPLANATION: An internal logic error occurred. These subcodes should never occur during normal operation.

SUBCODE INFORMATION:

X'1' An invalid message was sent by SNA Server Manager to a local server on the internal administration connection.

X'2' An unknown component has attempted to log an error.

X'6' The administration connection between SNA Server Manager and the local server (node) was lost while processing a command from SNA Server Manager.

X'7' Error in the format of the message sent from SNA Server Manager to the local server (node).

X'8' Buffer shortage or queue length exceeded. The administration connection between SNA Server Manager and the node has been damaged.

X'11E0' The local server (node) has found an error in its internal count of the number of messages in transit internally.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 3

(value) Node Configuration Error

EXPLANATION: The server (node) detected a configuration file problem caused by a logic error in the configuration program. These subcodes should not occur during normal operation.

SUBCODE INFORMATION:

X'1100' Incorrect Record Reference Number.

X'1101' Invalid length of product data record.

X'1102' Number of configured control blocks is valid.

X'1103' Error detected while resetting a control block.

X'1106' Configuration file is corrupted.

X'1107' Operator interface queue thresholds invalid.

X'1173' The SNA Server Manager program is not configured to allow permission to change session limits.

X'117A' Not enough room in configuration table.

ACTION: Provide network support personnel with the SNA Server configuration file. For information about the configuration file, see the Microsoft SNA Server Administration Guide.


Message 4

(value) Message Sequence Error

EXPLANATION: The server (node) received an invalid or unexpected message from a remote node on an SNA session. The remote system has a possible configuration or internal logic error.

SUBCODE INFORMATION:

X'1130' SNA pacing count error. The pacing count held exceeds the receive pacing window specified in the BIND, caused by a remote LU sending more than one pacing request within the window.

X'1132' The node received an FMD or DFC request when the data traffic state was not active.

X'1133' The node received a request with an invalid sequence number.

X'1139' The node received an STSN session control request while there was active data traffic on the session.

X'1182' The node received a BIND response when no BIND request was outstanding.

X'1183' The node received an UNBIND request for an inactive session, or an UNBIND response when no UNBIND request was outstanding.

X'11B2' The node received an unexpected BIS reply from a partner LU.

X'11B3' The node received an unexpected BIS request from a partner LU.

X'11B5' The node received an unexpected RTR from a partner LU.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 5

(value) Unsupported Session Control Request

EXPLANATION: The server (node) received an unexpected session control request. This is a protocol violation by the remote system. The remote system has a serious configuration or internal logic problem.

SUBCODE INFORMATION:

X'1137' The node received an SDT session control request.

X'1138' The node received an STSN session control request.

X'113A' The node received an RQR session control request.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 6

(value) Internal Network Management Logic Error (rc = value)

EXPLANATION: The server (node) detected a run-time error or resource shortage caused by internal logic errors in SNA Server Manager, the Common Service Verbs, or the 3270 emulator.

SUBCODE INFORMATION:

X'1184' Insufficient resources for concurrent network management activity. This is probably an SNA Server Manager program logic error, but can be caused by a large number of applications simultaneously issuing TRANSFER_MS_DATA.

X'118A' LU name specified by SNA Server Manager not found.

X'118B' Unexpected message.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 7

APPC session activation failure: LU inactive

Connection = value

LU alias = value

PLU alias = value

Mode name = value

LU address = value

EXPLANATION: The server (node) failed to activate an APPC session because the host has not sent an ACTLU request to the local dependent APPC LU. This error usually happens as the result of a mismatch between the host configuration and the SNA Server configuration.


Message 8

(value) Internal Protocol Violation

EXPLANATION: A protocol violation has occurred at the interface between the server (node) and another SNA component (for example, the emulator or link service).

SUBCODE INFORMATION:

X'1105' Insufficient space to copy data into node buffer.

X'1112' Received unknown message type at the node interface.

X'1144' Received illegal message at the node interface.

X'1151' Received unrecognized message from the link service component.

X'1174' Received invalid session limits message from SNA Server Manager.

X'1175' Received invalid CNOS command.

X'1188' Received invalid CNMS message.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 9

(value) Internal Message Sequence Error

EXPLANATION: Invalid or unexpected message received by the server (node) from another SNA Server component (for example, the emulator or link service).

SUBCODE INFORMATION:

X'1111' Received message from unrecognized component.

X'1117' Received an invalid message from a 3270 emulator.

X'1160' Unexpected response from link service.

X'1161' Unexpected message from link service.

X'1180' Unexpected message from emulator.

X'1181' Mode inconsistency: close received when not expected.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 10

(value) Resource Allocation Error

SUBCODE INFORMATION:

X'1179' An APPC session activation request from an unknown remote LU or an unknown mode (which would normally have been accepted using an implicit incoming remote LU or mode) could not be accepted. Either there was insufficient Windows NT memory available (system RAM or hard disk), or the maximum number of active APPC modes or remote LUs has already been reached.

ACTION: Try to free up Windows NT system memory and then retry. If the problem persists, provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and a description of how many sessions and services were running when the problem occurred. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 11

(value) Initialization Failure

EXPLANATION: This is an internal logic error in SNA Server, related to the configuration.

SUBCODE INFORMATION:

X'1177' Operator queues are full — messages have been lost.

X'1178' Insufficient resources for automatic session limit negotiation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 12

(value) Negative Response from Remote System (SENSE = value)

SUBCODE INFORMATION:

X'1118' The local server (node) received an SNA negative response on an SNA session from a remote system, which indicates a protocol violation by the 3270 emulator. The SNA sense code shown gives details of the type of error. See IBM Systems Network Architecture: Formats for an explanation of the sense code.

ACTION: If the error is accompanied by functional problems, use internal tracing to determine the cause of the problem. If the problem is associated with use of a user application (HLLAPI or APPC), report it to the application developer. Otherwise, check the SNA Server configuration, especially the configuration of the 3270 LU, and see that it corresponds to the configuration of the remote system.

If the problem persists, provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 13

(value) Message Sequence Error (SENSE = value)

EXPLANATION: The server (node) received an invalid or unexpected message from a remote node during an SNA session. The cause is probably a logic error in the remote system. The SNA sense data shown gives details of the type of error.

SUBCODE INFORMATION:

X'1141' Session-level protocol violation in an SNA message from the partner LU.

X'1142' Session-level protocol violation on host SSCP-to-LU session.

X'11B1' A BID request has failed the SNA receive request checks.

X'11C2' A partner LU has violated LU 6.2 protocols.

ACTION: See IBM Systems Network Architecture: Formats for an explanation of the SNA codes. Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 14

APPC session activation failure: INITSELF negative response received

Sense data = value

Connection = value

LU alias = value

PLU alias = value

Mode name = value

LU address = value

EXPLANATION: An APPC session has failed to activate because the host has rejected the SNA INITSELF request sent to initiate the session. The sense data contains more information about the reason for the rejection.

This error is usually caused by a mismatch between the host configuration and the SNA Server configuration. It may also be caused by some temporary error at the host (for example, the partner LU may be temporarily unavailable).


Message 15

APPC session activation failure: host session set-up error

Sense data = value

Connection = value

LU alias = value

PLU alias = value

Mode name = value

LU address = value

TH = value

RH = value

RU = value

EXPLANATION: An APPC session has failed to activate because the host has sent an SNA NOTIFY request indicating a problem connecting to the partner LU. The sense data contains more information about the reason for the failure.

This error is usually caused by a temporary error at the host (for example, in an SNA Server network consisting of multiple subdomains, the connection between the SSCP host and the host containing the partner LU may have failed). This error may also be caused by a mismatched configuration.

ACTION: Provide network support personnel with the information contained in this message.


Message 16

Invalid NOTIFY received on APPC LU-SSCP session

Sense data = value

Connection = value

LU name = value

LU address = value

Mode name = value

TH = value

RH = value

RU = value

EXPLANATION: An SNA NOTIFY request containing an invalid key, status field, or procedure correlator has been received from the host.

ACTION: Stop the session and restart with tracing on. Use entries in the trace file to help you and the host administrator determine the problem. For information about trace files, see the Microsoft SNA Server Administration Guide.


Message 17

APPC session activation failure: BIND negative response sent

Sense data = value

Connection = value

Session ID = value

LFSID = value

TH = value

RH = value

RU = value

EXPLANATION: An APPC session has failed to activate because an error was detected in the SNA BIND request sent by the partner LU. The sense data gives more information about the nature of the error.

This error is usually caused by a mismatch between the SNA Server configuration and the configuration of the partner LU's system (for example, the mode name specified in the SNA BIND request may not be configured in SNA Server).

ACTION: Provide network support personnel with the information contained in this message.


Message 18

APPC session activation failure: BIND negative response or UNBIND request received

Sense data = value

Connection = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: An APPC session has failed to activate because the partner LU rejected the SNA BIND request sent to initiate the session. The sense data gives more information on the reason for the rejection.

This error is usually caused by a mismatch between the SNA Server configuration and the configuration of the partner LU's system (for example, the mode name sent in the SNA BIND request was not acceptable to the partner LU).

ACTION: Provide network support personnel with the information contained in this message.


Message 19

(value) Security Violation: local LU = value, remote LU = value

EXPLANATION: This message may indicate that an unauthorized remote user is attempting to access your programs from a remote LU that imitates the remote LU that you configured.

SUBCODE INFORMATION:

X'11B4' The remote LU sent incomplete security key data for session-level security or has used the wrong key.

ACTION: Check that the remote LU is configured to use session-level security and is using the correct security key, that is, the same session-level security password that is configured for the remote APPC LU in the local SNA Server configuration.


Message 20

(value) Negative Response Received on Connection value (SENSE = value)

SUBCODE INFORMATION:

X'1123' Received and logged a negative response. This error is usually followed by a more specific error message from the SNA Server component processing the negative response.

ACTION: Look up the sense code in IBM Systems Network Architecture: Formats. If the sense code indicates a serious problem, contact support personnel for your network.


Message 21

(value) Negative Response Sent on Connection value (SENSE = value)

SUBCODE INFORMATION:

X'1124' A negative response was sent and logged. This error normally follows a more specific error message, depending on the type of negative response sent and its cause. The SNA sense data provides details about the type of error.

ACTION: See IBM Systems Network Architecture: Formats for an explanation of the sense data.


Message 22

APPC session activation failure: BIND negotiated parameters unacceptable

Sense data = value

Connection = value

LU alias = value

PLU alias = value

Mode name = value

LFSID = value

TH = value

RH = value

RU = value

EXPLANATION: An APPC session has failed to activate because the partner LU negotiated some parameters in the BIND, and the resulting values were unacceptable to the local LU. The sense data gives more information about which field was in error.

This error is usually caused by a mismatch between the SNA Server configuration and the configuration of the partner LU's system (for example, the maximum RU size requested by the partner LU may be smaller than the minimum RU size allowed by SNA Server).

ACTION: Provide network support personnel with the information contained in this message.


Message 23

Connection value using Link Service value failed

Qualifier = value

SUBCODE INFORMATION:

X'1152'

A link service reported a connection failure to the node.

When this error continues to occur during connection establishment, it is due to a mismatch between the parameters specified in SNA Server Manager and either the local hardware, the physical connection, or the remote system configuration.

If the problem occurs during data transfer, it can be due to an unreliable physical connection (such as noise on an SDLC line) or faulty hardware.

Return codes for different link service types are shown in the following sections.

SDLC Connections

The following are return codes for SDLC connections.

X'10'

All the link services configured for use by the connection were inactive.

X'16'

The link service has been terminated, either by a failure or by an operator action. If the termination is due to a failure, there should be other messages logged giving reasons for the failure. Check the actions for these messages.

X'87'

An invalid SDLC frame was received. This is a protocol error generated by the remote system.

X'89'

RD received. The remote system requested disconnection.

The next three codes indicate that the modem is disconnected or the remote system dropped the line.

X'11'

Data Set Ready (DSR) failure.

X'12'

Clear To Send (CTS) failure.

X'14'

Data Carrier Detect (DCD) failure.

The next three codes indicate that the remote end is inactive but has not broken the modem connection or that there is a very poor-quality line.

X'24'

Non-productive receive retry exceeded.

X'25'

Idle time-out retry exceeded.

X'29'

Connection problem.

The next two codes indicate a local hardware problem. Check the modem and adapter.

X'2D'

Abnormal response.

X'2E'

Write time-out retry exceeded.

The next three codes indicate that the remote end returned to initialization state.

X'15'

Connection terminated by host.

X'80'

DM received in Information Transfer state.

X'88'

RIM received.

The next four codes indicate that the remote end did not reply during a contact or disconnect attempt.

X'81'

Disconnect retry limit.

X'82'

Contact retry limit.

X'84'

No response retry limit. The remote end is not answering polls.

X'85'

Remote busy retry limit. The remote end failed to come out of "receiver not ready" (RNR) state.

X.25 Connections

The following are return codes for X.25 connections.

X'37'

Loss of a virtual circuit.

X'60'

The switched virtual circuit to the host has been cleared down (broken) either by the host or by the X.25 network itself.

X'61'

The permanent virtual circuit to the host has been reset (broken) either by the host or by the X.25 network itself.

X'62'

An attempt to connect to the host through a switched virtual circuit has failed.

Token Ring/802.2 Connections

The next three codes indicate a problem with the remote node (contact support personnel for your network).

X'29'

Remote node not active.

X'AE'

DISC/DM received.

X'AF'

Link lost.

The next three codes indicate a protocol violation on the LAN.

X'AB'

SABME received while connection active.

X'AC'

FRMR sent.

X'AD'

FRMR received.

DFT Connections

The DFT outage codes are derived from the line check codes generated by the 3X74 control unit. The line check code will have been logged on a previous #261 message. Take the outage code from the message, convert it to decimal, and add 484 to it. The result is the line check code. Here is an example: an outage code of 11 converts to 17 in decimal. 484 + 17 = 501, which is the line check code. Look up the line check code in the maintenance information manual for your control unit and follow the actions indicated there.

X'11'

Data Set Ready (DSR) failure.

X'14'

Data Carrier Detect (DCD) failure.

X'15'

Connection terminated by host.

ACTION: Check the return code shown, any events logged by the link service, and the local configuration and hardware to determine what the problem is. If the frequency of the problem is unacceptable, contact network support personnel.


Message 24

APPC session activation failure: connection failed

Connection = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: An APPC session has failed to activate because the connection has failed.

ACTION: Check event log entries for the reason for the connection failure, correct the errors, and retry the session activation.


Message 25

APPC session activation failure: connection disabled

Connection = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: An APPC session has failed to activate because the connection was configured to be started "By Administrator," and it has not been started.

ACTION: If the session is required, activate the connection and retry the session.


Message 26

APPC session activation failure: session limit error

Connection = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: An APPC session has failed to activate because the session limits for the mode have not been negotiated correctly. This error is usually caused by a mismatch between the SNA Server configuration and the configuration of the partner LU's system (for example, the requested mode's session limits may not be configured to correspond to the local mode's limits).

ACTION: Correct the configuration error or contact support personnel for your network.


Message 27

Connection activated successfully

Connection = value

EXPLANATION: The connection was activated, either because an administrator activated it, or because it was needed for activating a session. No action is necessary.


Message 28

Connection deactivated normally

Connection = value

EXPLANATION: The connection was deactivated, either because an administrator deactivated it, or because no more sessions were using it. No action is necessary.


Message 29

Internal Gateway error

Sense code = value

Parameter 1 = value

Parameter 2 = value

Parameter 3 = value

Parameter 4 = value

Parameter 5 = value

Parameter 6 = value

EXPLANATION: An internal error has occurred in the SNA Server gateway function.

ACTION: Provide network support personnel with the information contained in this message.


Message 30

(value) Conversation Error

SUBCODE INFORMATION:

X'1172' An LU conversation being used by SNA Server Manager to establish session limits with a partner LU has failed. Messages following this message will indicate the reasons for the failure.

ACTION: Check the other error messages and follow the actions specified for them.


Message 31

(value) SNA Server Manager command failure, rc = value

EXPLANATION: A command issued by SNA Server Manager failed.

SUBCODE INFORMATION:

X'06'

COMMAND_IN_PROGRESS: This code should not normally occur.

X'07'

COMMAND_NOT_RECOGNIZED: This code should not normally occur.

X'09'

SESSION_ACTIVATION_FAILED: An attempt to start an APPC session via SNA Server Manager failed. This log is accompanied by one of the APPC session activation failure messages (message 7, 14, 15, 17, 18, 22, 24, 25, or 26). These messages provide more information about the failure.

X'0A'

COMMAND_RACE_REJECT: A change number of sessions (CNOS) request (either Activate or Deactivate APPC sessions) made through SNA Server Manager failed because the partner LU was also trying to change the session limit for the specified mode. Retry the command.

X'0B'

SESSION _LIMIT_CLOSED: A CNOS request made through SNA Server Manager failed because the partner LU will not allow the session limit for the specified mode to be raised above zero. This may not be a permanent condition; try the CNOS request later. If the problem persists, contact support personnel for your network.

X'0C'

SESSION_LIMIT_NOT_ZERO: An activate session request made through SNA Server Manager has failed because the session limit was not zero. This may occur because the partner LU initialized the session limit immediately before SNA Server Manager attempted to do so. No action is required.

X'0D'

LU_SESSION_LIMIT_EXCEEDED: SNA Server Manager issued an activate session request that violates the session limit for the LU.

In most cases, the LU session limit should be larger than the sum of the session limits of all the modes associated with the LU (remembering to allow for SNASVCMG modes). If this is not the case, some modes may not available, or may only allow a reduced number of sessions.

X'0E'

REQUEST_EXCEEDED_MAXIMUM_ALLOWED: This code should not normally occur.

X'0F'

RESOURCE_FAILURE_NO_RETRY: A CNOS request failed to complete because of a permanent resource failure. This error is caused by the partner LU violating the CNOS protocol. Obtain a trace of the error, and contact your network support personnel with the trace file and the event log file(s) related to SNA Server.

X'10'

ALLOCATION_ERROR: A CNOS request failed because no SNASVCMG session could be allocated to perform the CNOS exchange. This may occur because the connection required has not been activated, or the partner LU rejected the BIND request. If the error occurred because the connection was not active, activate it and retry the request. If the BIND was rejected, contact your network support personnel with the event log file(s) related to SNA Server.

X'11'

UNRECOGNIZED_MODE_NAME: A CNOS request failed because the partner LU does not recognize the specified mode name. This error signifies a configuration mismatch between the local LU and the partner LU.

X'12'

PARAMETER_ERROR_BAD_LU_NAME: This code should not normally occur.

X'13'

PARAMETER_ERROR_BAD_RESOURCE NAME: This code should not normally occur.

X'14'

PARAMETER_ERROR_MISSING_PARAMETERS: This code should not normally occur.

X'16'

PARAMETER_ERROR_BAD_ADDRESS: This code should not normally occur.

X'17'

PARAMETER_ERROR_SECURITY_ERROR: This code should not normally occur.

X'18'

PARAMETER_ERROR_MIN_GT_MAX: This code should not normally occur.

X'1A'

RESOURCE_ACTIVE: SNA Server Manager tried to activate a connection when it was already active. This may occur as part of normal operation, for example, if an application activates the connection immediately before SNA Server Manager issues the command. No action is required.

X'1C'

RESOURCE_INACTIVE: SNA Server Manager tried to deactivate a connection when it was already inactive. This may occur as part of normal operation, for example, if the connection is deactivated because of an outage immediately before SNA Server Manager issues the command. No action is required.

X'1D'

NO_LINK: SNA Server Manager tried to activate a switched connection, but all the appropriate link services are being fully used. Deactivate unused connections using the appropriate link services and retry the command.

X'1E'

NO_PRIVILEGE: This code should not normally occur.

X'1F'

PARAMETER_ERROR_FORCE_ERROR: This code should not normally occur.

X'22'

ABEND_PROG_ERROR: This code should not normally occur.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, the SNA Server configuration file, internal trace file(s), and the number and description of the displayed return code. For information about SNA Server log files, configuration files, and trace files, see the Microsoft SNA Server Administration Guide.


Message 32

SSCP-PU session activated

Connection = value

EXPLANATION: The host has successfully activated the SSCP-to-PU session with a server (node) on the specified connection. No action is required.


Message 33

SSCP-PU session deactivated

Connection = value

EXPLANATION: This is a status message. The host has shut down the SSCP-to-PU session with a server (node) on the specified connection. No action is required.


Message 34

SSCP-LU session activated

Connection = value

LU name = value

LU address = value

EXPLANATION: The host has successfully activated the SSCP-to-LU session with a server (node) on the specified connection. No action is required.


Message 35

SSCP-LU session deactivated

Connection = value

LU name = value

LU address = value

EXPLANATION: This is a status message. The host has shut down the SSCP-to-LU session with a server (node) on the specified connection. No action is required.


Message 36

APPC session activated

Connection = value

LU alias = value

PLU alias = value

Mode name = value

Session ID = value

LFSID = value

EXPLANATION: The host has successfully activated the LU-to-LU session with a server (node) on the specified connection. No action is required.


Message 37

APPC session deactivated normally

Connection = value

LU alias = value

PLU alias = value

Mode name = value

Session ID = value

LFSID = value

EXPLANATION: This is a status message. The host has deactivated the LU-to-LU session with a server (node) on the specified connection. No action is required.


Message 38

APPC session deactivated abnormally

Qualifier = value

Connection = value

LU alias = value

PLU alias = value

Mode name = value

Session ID = value

LFSID = value

EXPLANATION: An APPC session has been deactivated abnormally. The qualifier listed above corresponds to one of the following:

0002 The session was deactivated because of a temporary (Retry) error, and may be retried.

0003 The session was deactivated because of a permanent (No retry) error, such as a parameter mismatch. Contact the administrator of the partner LU's system to determine which parameters are mismatched.


Message 39

Connection value failed: No link service available


Message 40

value not configured in value

EXPLANATION: The administrator attempted to start a server (node) but supplied a server name that was not in the configuration.

ACTION: Use SNA Server Manager to check for the correct server (node) name in the configuration, and retry.


Message 41

NetView Management Connection information not found in value

EXPLANATION: In the configuration file, there was no connection specified for sending and receiving NetView management data.

The connection to use for NetView management data can be specified using SNA Server Manager. To specify the connection, from the Options menu, choose NetView, and then, in the NetView Options dialog box, select a connection name. For more information, see the Microsoft SNA Server Administration Guide.

ACTION: This message probably indicates an internal error in SNA Server Manager. Provide network support personnel with a copy of the SNA Server configuration file. For information about the configuration file, see the Microsoft SNA Server Administration Guide.


Message 42

value record in value is too short

EXPLANATION: The configuration file information about the server (node) was invalid. This indicates an internal error in SNA Server Manager.

ACTION: Provide network support personnel with a copy of the SNA Server configuration file. For information about the configuration file, see the Microsoft SNA Server Administration Guide.


Message 43

Network management record in value is too short

EXPLANATION: In the configuration file, the listing for the connection for sending and receiving NetView management data was invalid. This indicates an internal error in SNA Server Manager.

ACTION: Provide network support personnel with a copy of the SNA Server configuration file. For information about the configuration file, see the Microsoft SNA Server Administration Guide.


Message 44

Session limit exceeded for local LU value: session limit for mode value is zero

EXPLANATION: The node failed to set the session limits for an APPC mode because it would cause the local LU session limit to be exceeded.

ACTION: Decrease the mode session limit, or increase the local LU session limit.


Message 45

value Initially active connection value can't be activated because the number of connections exceeds the maximum for the link


Message 46

Connection value failed: the link role is the same as the link role of the remote computer


Message 47

Connection value failed: Node ID rejected by remote computer


Message 48

Incorrect parameters on starting the local SNA Server

EXPLANATION: An internal error occurred during an attempt to start the local server (node). This error should not occur in normal operation.


Message 49

Connection value failed: Node ID from remote computer was rejected

(value value value value)


Message 50

Security Violation: Local LU = value, Partner LU = value

EXPLANATION: A remote TP caused a violation of APPC TP security. The LU names are given here for information. This message will be followed by another message which will give more details about the security violation.


Message 51

User ID value not found

EXPLANATION: A remote APPC TP supplied a user ID not recognized by SNA Server. This error occurs when a remote APPC TP attempts to establish a conversation with an SNA Server TP configured to use conversation-level security.

ACTION: Check the user ID against the configured IDs.

This message may indicate that an unauthorized remote user is attempting to access your programs from a remote LU that imitates the remote LU that you configured.


Message 52

Password not supplied

EXPLANATION: A remote APPC TP did not supply a password during an attempt to establish a conversation with an SNA Server TP configured to use conversation-level security. A TP configured to use conversation-level security does not accept an "already verified" indication from the remote LU.

An error in the remote TP or in the SNA Server configuration can cause this error to occur.

ACTION: Check whether the remote TP is configured to use conversation-level security.

This message may indicate that an unauthorized remote user is attempting to access your programs from a remote LU that imitates the remote LU that you configured.


Message 53

Password mismatch, User ID = value

EXPLANATION: An invalid password was sent by a remote APPC TP during an attempt to establish a conversation with an SNA Server TP configured to use conversation-level security. The user ID supplied by the remote TP is shown. An error in the remote TP or in the SNA Server configuration can cause this error to occur.

ACTION: Check with the remote user whose user ID is shown on this message.

This message may indicate that an unauthorized remote user is attempting to access your programs from a remote LU that imitates the remote LU that you configured.


Message 54

User ID not supplied

EXPLANATION: A remote APPC TP has not supplied a user ID when attempting to establish a conversation with an SNA Server TP configured to use conversation-level security. An error in the remote TP or in the SNA Server configuration can cause this error to occur.

ACTION: Check whether the remote LU is configured to use conversation-level security.

This message may indicate that an unauthorized remote user is attempting to access your programs from a remote LU that imitates the remote LU that you configured.


Message 55

No incoming connection matched info in XID from remote MAC address value.


Message 56

Connection value failed: XID rejected by remote computer


Message 57

Internal timer error. Incorrect number of timing control blocks

Timer type value

Expected number of control blocks value

Overrun value

EXPLANATION: An internal error was detected processing timers within SNA Server. This error should not occur in normal operation


Message 58

Internal timer error. Incorrect number of timed out control blocks

Timer type value

Overrun value

EXPLANATION: An internal error was detected processing timers within SNA Server. This error should not occur in normal operation


Message 60

Failed to invoke APPC TP value (value), sense data = value

EXPLANATION: An attempt to invoke the APPC TP shown has failed. The error will be reported to the invoking TP on the remote system with the following primary return code:

AP_ALLOCATION_ERROR. The sense data shown is the secondary return code, which will be one of the following hexadecimal values:

X'084B6031' AP_TRANS_PGM_NOT_AVAIL_RETRY

X'084C0000' AP_TRANS_PGM_NOT_AVAIL_NO_RETRY

X'10086021' AP_TP_NAME_NOT_RECOGNIZED

X'10086031' AP_PIP_NOT_ALLOWED

X'10086032' AP_PIP_NOT_SPECIFIED_CORRECTLY

X'10086034' AP_CONVERSATION_TYPE_MISMATCH

X'10086041' AP_SYNC_LEVEL_NOT_SUPPORTED

ACTION: Refer to the Microsoft SNA Server APPC Programmer's Guide for explanations of these error codes.


Message 70

APPC TP started locally:

TP_ID = value

TP name = value

EXPLANATION: The APPC TP shown has started. The TP_ID that appears is used to identify later events for this TP. If the TP ends abnormally, there will be other error messages indicating the nature of the problem.


Message 71

APPC TP ended:

TP_ID = value

EXPLANATION: An APPC TP has ended. The TP_ID that appears was displayed on a previous message providing the TP name. No action is necessary.


Message 72

APPC conversation started locally:

TP_ID = value

Conv_ID = value

Dest TP name = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: A local APPC TP started a conversation with a partner LU. The TP_ID that appears was displayed on a previous message. The TP_ID and Conv_ID are used to identify later events for this conversation. No action is necessary.


Message 73

APPC TP and conversation started remotely:

TP_ID = value

Conv_ID = value

TP name = value

LU alias = value

PLU alias = value

Mode name = value

User ID = value

EXPLANATION: A remote APPC TP started a conversation with a local TP. The TP_ID and Conv_ID that appear are used to identify later events for this conversation. No action is necessary.


Message 74

APPC conversation ended:

TP_ID = value

Conv_ID = value

EXPLANATION: An APPC conversation has ended. The TP_ID and Conv_ID were shown on a previous message.

ACTION: If an abnormal termination occurs, review the previous messages that indicated errors in this conversation.


Message 75

APPC error sent:

Sense data = value

TP_ID = value

Conv_ID = value

Log data value

EXPLANATION: A local APPC TP sent an error to the partner TP by issuing an [MC_]SEND_ERROR or [MC_]DEALLOCATE (ABEND) verb. The TP_ID and Conv_ID in this message were shown on a previous message. This message is followed by one or more messages containing log data supplied by the TP. The SNA sense data provides details about the error type.

ACTION: See IBM Systems Network Architecture: Formats for an explanation of the sense data.


Message 76

APPC error received:

Sense data = value

TP_ID = value

Conv_ID = value

Log data value

EXPLANATION: The partner APPC TP sent an error to the local TP by issuing an [MC_]SEND_ERROR or [MC_]DEALLOCATE (ABEND) verb. The message is also logged if the partner TP failed to start. The TP_ID and Conv_ID in this message were shown in a previous message. This message is followed by one or more messages containing log data supplied by the TP. The SNA sense data provides details about the error type.

ACTION: See IBM Systems Network Architecture: Formats for an explanation of the sense data.


Message 79

TP Aborted:

TP_ID = value


Message 90

APPC protocol violation:

Sense data = value

TP_ID = value

Conv_ID = value

EXPLANATION: A protocol violation was detected on an APPC conversation. The TP_ID and Conv_ID in this message were shown on a previous message. The conversation failure is reported to the local TP with a return code of AP_CONV_FAILURE_NO_RETRY. The SNA sense data provides detail about the error type.

ACTION: See IBM Systems Network Architecture: Formats for an explanation of the sense data.


Message 91

APPC conversation failure:

TP_ID = value

Conv_ID = value

EXPLANATION: APPC conversation failed because of a connection failure. The connection failure is reported to the local TP with a return code of AP_CONV_FAILURE_RETRY.

One possible cause of this error is that the partner TP issued a TP_ENDED(HARD).

ACTION: Other logged messages will indicate the reasons for the connection failure; follow the actions in those messages.


Message 92

APPC TP detected abend of SNA subsystem

TP_ID = value

Conv_ID = value

EXPLANATION: A connection was lost or has been broken between an APPC TP, the local APPC LU it was using, and the local node. The connection failure is reported to the TP with a return code of AP_COMM_SUBSYSTEM_ABENDED.

ACTION: Check for failure indications in the event log and follow the recommended actions.


Message 93

APPC local conversation start failed:

Primary_rc = value

Secondary_rc = value

TP_ID = value

Dest TP name = value

LU alias = value

PLU alias = value

Mode name = value

EXPLANATION: An attempt to start an APPC conversation locally using the verb [MC_]ALLOCATE failed.

ACTION: Refer to the Microsoft SNA Server APPC Programmer's Guide for information about the displayed primary_rc and secondary_rc values.


Message 94

APPC remote conversation start failed:

Primary_rc = value

Secondary_rc = value

TP name = value

EXPLANATION: An invokable APPC TP configured on SNA Server has issued a RECEIVE_ALLOCATE verb that failed.

ACTION: Refer to the Microsoft SNA Server APPC Programmer's Guide for information about the displayed primary_rc and secondary_rc values.


Message 95

APPC given bad event handle or callback address value


Message 96

Local APPC TP start failed:

Primary_rc = value

Secondary_rc = value

TP name = value


Message 101

(value) Internal Protocol Violation

EXPLANATION: The component logging this error received an invalid message from another SNA Server component. This is an internal error and should not occur during normal operation.

SUBCODE INFORMATION:

0B49 Wrong length for Locality Data.

0A08 Invalid message discarded.

0A40 Unrecognized Open request type.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), the dump file, and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 102

(value) Internal Error

SUBCODE INFORMATION:

X'0B02' A dynamic storage allocation request has failed.

X'0BC1' Buffer header pointer is corrupted.

X'0BC3' Corruption of internal free buffer pool.

X'0BC5' Free ready pool is empty.

X'0BC6' Free active pool is empty.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), the dump file, and the number and description of the displayed subcode. For information about SNA Server log, trace, and dump files, see the Microsoft SNA Server Administration Guide.


Message 103

(value) Configuration File Format Error

EXPLANATION: The node configuration data read from the configuration file is invalid.

SUBCODE INFORMATION:

X'0A00' The record was not found in the configuration file, COM.CFG.

X'0A06' The destination name was not found in the configuration file.

X'0A09' The resource ID was incorrect.

X'0A43' The Record Reference Number was repeated in the configuration file.

X'0A44' The Reference Number in the configuration file was too big.

X'0A45' The record was not found in the configuration file.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, the SNA Server configuration file, and the number and description of the displayed subcode. For information about SNA Server log files and the configuration file, see the Microsoft SNA Server Administration Guide.


Message 104

(value) Message Sequence Error

EXPLANATION: This is an internal logic error. An SNA Server component received an unexpected message from another SNA Server component.

SUBCODE INFORMATION:

X'0B43' Invalid or unexpected message received.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 108

(value) Message Routing Error

EXPLANATION: This is an SNA Server internal logic error.

SUBCODE INFORMATION:

X'0B41' Path error during initialization.

X'0B42' Path error after initialization.

X'0B45' Error in internal addressing.

X'0B47' Illegal internal address.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 110

(value) Resource Allocation Error

EXPLANATION: This is an internal logic error.

SUBCODE INFORMATION:

X'0B00 There were insufficient buffers during run-time code processing of the configuration file.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 120

(value) Shortage Of Buffers

EXPLANATION: There are insufficient buffers for the component to continue processing.

ACTION: Use the COMBUF Registry variable to allocate more buffers to the component. If increasing the size of the buffer pool does not solve the problem, it may indicate an internal error. Provide network support personnel with the event log file(s) related to SNA Server, as well as the dump file.

For information about SNA Server log and dump files, see the Microsoft SNA Server Administration Guide. For information about COMBUF, see the Appendix C, "Registry and Environment Variables for SNA Server."


Message 121

Fatal error occurred, product ID = value, error code = value

EXPLANATION: This is an internal error that should never occur during normal operation.

ACTION: Make a note of the product ID and error code displayed, and provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 127

Link protocol DLL does not contain expected entry points


Message 128

Can't locate IHV DLL value


Message 129

Configuration information for SNALink value is not present


Message 151

(value) Internal Protocol Violation

EXPLANATION: An internal protocol violation occurred. This is due to an internal logic error in SNA Server.

SUBCODE INFORMATION:

X'0140' Invalid message type.

X'0141' Invalid open type.

X'0142' Invalid close type.

X'0143' Invalid DLC status message.

X'0144' Invalid destination routing information.

X'0145' Illegal DLC message for a link.

X'014C' Invalid type qualifier.

X'014D' No element on DLCDATA message.

X'014E' Invalid routing information on message.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, the dump file, and the number and description of the displayed subcode. For information about SNA Server log and dump files, see the Microsoft SNA Server Administration Guide.


Message 152

(value) Open from node rejected, rc = value

SUBCODE INFORMATION:

X'0100' The SDLC link service rejected an Open request from the local server (node), which indicates an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, as well as the return code displayed with this error. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 154

(value) Internal Message Sequence Error

EXPLANATION: The node received an invalid or unexpected message. This is an internal logic error in the node component detected by the link service.

SUBCODE INFORMATION:

X'0147' Link not open — cannot receive messages.

X'0148' Station not open — cannot receive messages.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), the dump file, and the number and description of the displayed subcode. For information about SNA Server log, trace, and dump files, see the Microsoft SNA Server Administration Guide.


Message 160

(value) Resource Allocation Error

EXPLANATION: Severity 16.

SUBCODE INFORMATION:

X'014B' SNA Server is unable to send a message to the node due to a buffer shortage. This is an internal error that should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), and the dump file. For information about SNA Server log, trace, and dump files, see the Microsoft SNA Server Administration Guide.


Message 162

(value) Protocol Violation

EXPLANATION: The adjacent SDLC link station caused a protocol violation. This is probably a configuration or internal logic error in the remote system.

SUBCODE INFORMATION:

X'0146' The SDLC frame was too short — there is no address or control.

X'014A' Received NR value is invalid.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s), and the number and description of the displayed subcode. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 165

Establishing connection value through SDLC link service value
Please dial value within value s.

EXPLANATION: A switched, manual-dial connection was activated using the specified link service. Dial the specified number within the specified time, so that communication can be established over the connection.


Message 166

The SNA Server software is dialing connection value through SDLC link service value

EXPLANATION: A switched connection that is configured for automatic dialing by SNA Server was started. The pop-up will disappear after approximately 10 seconds. No action is necessary.


Message 167

Initializing connection value from value through link service value

EXPLANATION: An SDLC connection is being started. No action is necessary.


Message 168

Link device driver value error on function value, rc = value

EXPLANATION: An internal error has been reported to the SDLC device driver.

ACTION: Provide network support personnel with the function number and return code shown on this message.


Message 169

Failed to Open device driver value. Windows NT rc = value

EXPLANATION: An error occurred during an attempt to open the SDLC device driver. The return code from the OpenFile call is shown.

ACTION: Check the OpenFile return code.


Message 170

Initialization failed for link service value, used by connection value

EXPLANATION: The SDLC link service could not be initialized. A previous message gives the reason for failure.

ACTION: Refer to the previous message.


Message 171

Initialization for driver value OK, trying to connect

EXPLANATION: The indicated SDLC driver has been initialized and the SDLC link service is attempting to establish a connection.

ACTION: No action is necessary.


Message 173

Unknown modem type: value

EXPLANATION: This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and also the modem number included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 174

Failed to initiate connection value through link service value

EXPLANATION: Failed to establish an autodial connection.

ACTION: Check the modem connections, internal functions, and dial data. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 175

Modem shows DSR BEFORE dialing, for connection value through link service value

EXPLANATION: The DSR signal from the modem, normally low until dialing is started, was already high before dialing. The modem may not be functioning correctly.

ACTION: Check the modem documentation. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 176

No DSR for modem used by connection value through link service value. Check modem power and cabling

EXPLANATION: The DSR signal from the modem has not come up, indicating that the modem is not functioning correctly.

ACTION: Check the modem connections and the modem's documentation for correct settings. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 177

The sending of the phone number from SNA Server to the modem failed: no CTS. Check modem state, power, and cabling, for the modem used by connection value through link service value.

EXPLANATION: The dialing process failed and there is no CTS signal from the modem.

ACTION: Check the modem connections and the modem. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 178

The sending of the phone number from SNA Server to the modem failed; DSR steady. Check state of modem used by connection value through link service value.

EXPLANATION: The dialing process initiated by SNA Server failed; the modem is not dialing when the dial command is sent by SNA Server.

ACTION: Check the modem connections and the dial string sent to the modem. If the connections and dial string are OK, then the modem may not be functioning correctly. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 179

Connection value through link service value has been closed

EXPLANATION: The SDLC connection through the indicated link service has been closed. No action is necessary.


Message 180

DSR up. Modem OK for connection value through link service value

EXPLANATION: The modem initialization for the connection shown has completed. No action is necessary.


Message 181

DSR dropped: connection value through link service value ended

EXPLANATION: The DSR signal from the modem has been dropped, which indicates that the connection shown has ended.

ACTION: If the connection failed while in use, other messages should be logged giving reasons for the failure. If this message is unexpected, refer to any messages that may have occurred prior to this message.


Message 182

Connection failure, code = value

Cause Data = value

Link Role = value

Remote Node Type = value

EXPLANATION: Cause data is a list of the failure causes from the Failure subvector in the alert. Link role and remote node type are as described in the Link Connection Subsystem Configuration Data subvector in the alert.

A connection failure can be due to a station outage, rather than a link outage. If it is due to a station outage — which can be recognized by outage code values of X'80' or higher — then message #183 will also be logged.

ACTION: No action is necessary.


Message 183

Detailed diagnostic data for station value:

SBSY CFTX CFRX V(S) V(R) N(R) OSFC T1CT

value

EXPLANATION: The value following "station" is the station address as given in the Detail Qualifier subvector in the alert.

The other fields are all data from the Link Station Data subvector, as follows:

SBSY Link station state: 80 or 40 (Local or remote station sending RNR)

CFTX Last SDLC control field sent

CFRX Last SDLC control field received

V(S) N(S) count

V(R) N(R) count

N(R) Last received N(R)

OSFC Outstanding frame count

T1CT Reply timer expiration count

ACTION: No action is necessary.


Message 184

Link statistics:

TXIOK TXIER RETXI RXIOK RXIER

Current value

Accumulated value

RXINV RXFRM TXFRM RXLST FRMRT

Current value

Accumulated value

CTSER DSRUP DSRDN DSRER IDLTO

Current value

Accumulated value

FRMRR DMAUR DMAOR TXERR RXOVR

Current value

Accumulated value

EXPLANATION: SDLC link services maintain counts of data traffic and error events that are logged whenever a counter "wraps," or whenever a connection through the link service terminates. There are counters for each of 20 types of event. Current counters show the values since the statistics were last logged. They are reset to zero after being logged. Accumulated counters are total counts kept from the time the SDLC link service was started.

The counters have the maximum value of 32,767. When any "current" counter reaches this value, the counters are logged and reset. "Accumulated" counters are frozen when they reach the maximum.

The individual counters are as follows:

TXIOK Information frames successfully transmitted

TXIER Information frames not successfully transmitted

RETXI Re-transmitted information frames

RXIOK Information frames successfully received

RXIER Frames not successfully received

RXINV Invalid frames received

RXFRM Total number of frames received

TXFRM Total number of frames sent

RXLST Frames received and then discarded

FRMRT 'FRMR' frames transmitted

CTSER Clear to Send drops during transmission

DSRUP DSR up before switched connection attempted

DSRDN No DSR before switched connection timeout

DSRER DSR lost before connection established

IDLTO Link inactivity timeout

FRMRR 'FRMR' or 'DM' received

DMAUR Transmitter interrupts missed

DMAOR Frames received longer than the configured max

TXFRR Failed to transmit a frame

RXOVR Receiver interrupts missed

The counts are also sent as an alert NMVT (subtype 0x0025) on the NetView management connection, if it is active. See message #540.

ACTION: No action is necessary.


Message 187

Unable to initiate connection value through link service value because the modem is already showing DSR ON. Reset the modem and retry.

EXPLANATION: This message is displayed at the same time that message #175 is logged.

ACTION: Check the modem documentation. See the Microsoft SNA Server Administration Guide for more information on the use of modems.


Message 188

Warning: Non-productive receive timeout on connection value through driver value. Contact with the host may have been lost.

EXPLANATION: The indicated connection, using the indicated SDLC driver, has not received anything from the host for 1 minute. The connection may have been lost. If the connection has been lost, after 3 minutes, it fails and message #23 is logged. If the host is very slow at polling its remote nodes, it is possible that the connection is not lost.

ACTION: If the message persists, contact your host administrator.


Message 189

SNA Server could not open value to use for auto-dialing on connection value.

EXPLANATION: Another application is probably using the requested COM port. You must stop that application before this connection will start.

ACTION: Stop the application and retry this connection.


Message 197

SDLC link service value not configured in value

EXPLANATION: You tried to start an SDLC link service with a name that was not in the configuration file.

ACTION: Use SNA Server Manager to check the correct service name, and retry.


Message 198

Incorrect parameters on starting SDLC link service

EXPLANATION: This internal error should never occur during normal operation.

ACTION: Contact network support personnel at your site.


Message 199

Secondary return code = value


Message 206

Incoming call discarded as value inactive

EXPLANATION: An incoming call to the node shown was discarded.

ACTION: Refer to information on configuring local servers, and link services usage parameters.


Message 210

Failed to get required memory resources

EXPLANATION: There is not enough memory to start the DLC (802.2) link service.

ACTION: Stop any unnecessary programs running on your computer and retry.


Message 211

Internal Error (value)

EXPLANATION: An internal logic error has been encountered. This error should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), and the error code included in this message. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 217

Adapter initialization error

local MAC address = value

EXPLANATION AND ACTION: The DLC (802.2) link service detected an error while trying to initialize the NDIS adapter. This error can be caused by one of the following conditions:

  • Token ring cable or MAU fault. Check the cable from the PC to the MAU and try again. If the problem persists, replace the cable and/or the MAU and try again.
  • Duplicate network address on ring. Check the address of this adapter against the addresses of all the other adapters on the same ring. If there is a duplicate, change one of the addresses and try again.
  • Temporary contention condition on ring. These errors are only temporary and should clear themselves. The token ring service will attempt to initialize the adapter after a delay, and initialization should then be successful.
  • Adapter speed mismatch. Check that the token ring adapter is set for the same speed as the rest of the adapters on the ring. If not, change the speed and try again.
  • Token ring adapter hardware fault. Replace the token ring adapter and retry.

If none of these actions solves the problem, contact support personnel for your network.


Message 218

Adapter check: microcode abnormally terminated

local MAC address = value

local ring number = value

EXPLANATION: The token ring adapter microcode has terminated abnormally. All connections will fail.

ACTION: Run any diagnostics provided with the token ring adapter, then contact the vendor of the token ring adapter.


Message 219

Adapter check: receive queue overrun

local MAC address = value

local ring number = value

EXPLANATION: The NDIS adapter was unable to receive an incoming frame due to a shortage of buffer space. All connections will fail.

ACTION: Run any diagnostics provided with the NDIS adapter, then contact the vendor of the NDIS adapter.


Message 220

Adapter check (value)

local MAC address = value

local ring number = value

EXPLANATION: The NDIS adapter has detected a hardware or microcode error.

ACTION: Run any diagnostics provided with the NDIS adapter, then contact the vendor of the NDIS adapter.


Message 221

Network status: lobe wire fault

local MAC address = value

EXPLANATION: The NDIS adapter has detected an open or short circuit on the lobe wire circuit. The adapter will be closed and all connections will fail.

ACTION: Check all cables between the adapter and the MAU, and retry. If the error persists, contact support personnel for your network.


Message 222

Network status: auto-removal error

local MAC address = value

EXPLANATION: The NDIS adapter has detected a hardware fault and removed itself from the ring. All connections will fail.

ACTION: Check all cables between the adapter and the MAU, and retry. If the error persists, contact support personnel for your network.


Message 223

Network status: remove command received

local MAC address = value

local ring number = value

EXPLANATION: A command was received forcing the NDIS adapter to remove itself from the ring. All connections will fail.

ACTION: Contact support personnel for your network to find the reason for the remove command.


Message 224

System action exception

EXPLANATION: A user application has made a call to the DLC driver with the SYSTEM_ACTION_FLAG set.

ACTION: Contact your support personnel for help.


Message 225

PC detected error (value)

local MAC address = value

local ring number = value

EXPLANATION: The DLC device driver has detected an unacceptable error (such as an unexpected return code from Windows NT). The adapter will be closed, and all connections will fail.

ACTION: If the error persists, contact support personnel for your network.


Message 226

Connection lost

Connection = value

Local MAC address = value

Local ring number = value

Remote MAC address = value

Routing data = value

Source SAP = value

Destination SAP = value

Connection data = N(S) N(R) PFRC LRNR FRMD CRCV CSND LKST
value

EXPLANATION: The specified connection was lost, either because of some problem with the local NDIS adapter, a problem at the remote adapter, or a problem in the network itself (for example, a bridge failure).

The connection data fields are as follows:

N(S) N(S) value of last transmitted frame

N(R) N(R) value of last transmitted frame

PFRC Number of I-frames that have not been acknowledged

LRNR N(R) value of last received frame

FRMD Frame modulus (should be 128)

CRCV Last command/response received

CSND Last command/response sent

LKST Link state

Bit 6 — local busy

Bit 4 — remote busy

ACTION: If another error message signifies a local adapter fault, perform the action recommended in that message. If no error message signifies a problem with the local adapter, contact support personnel for your network.


Message 227

FRMR received (value)

Connection = value

Local MAC address = value

Local ring number = value

Remote MAC address = value

Routing data = value

Source SAP = value

Destination SAP = value

Connection data = N(S) N(R) PFRC LRNR FRMD CRCV CSND LKST
value

EXPLANATION: A FRMR frame was received on this connection indicating that the local station sent a frame containing an error. The connection will be deactivated.

The FRMR code takes the following values:

01 Invalid N(R) value sent

02 Maximum I-field length exceeded

03 Invalid or unsupported command/response sent

04 I-frame sent when not permitted

ACTION: See message #226 for details of the connection data.

If this problem persists, contact support personnel for your network.


Message 228

FRMR sent (value)

Connection = value

Local MAC address = value

Local ring number = value

Remote MAC address = value

Routing data = value

Source SAP = value

Destination SAP = value

Connection data = N(S) N(R) PFRC LRNR FRMD CRCV CSND LKST
value

EXPLANATION: A FRMR frame was sent on this connection indicating that the remote station sent a frame containing an error. The connection will be deactivated.

The FRMR code takes the following values:

01 Invalid N(R) value received

02 Maximum I-field length exceeded

03 Invalid or unsupported command/response received

04 I-frame received when not permitted

ACTION: See message #226 for details of the connection data.

If this problem persists, contact support personnel for your network.


Message 229

SABME received when connection active

Connection = value

Local MAC address = value

Local ring number = value

Remote MAC address = value

Routing data = value

Source SAP = value

Destination SAP = value

Connection data = N(S) N(R) PFRC LRNR FRMD CRCV CSND LKST
value

EXPLANATION: A SABME frame was received from the remote station while the connection was activated. The connection will be deactivated. This may be caused by an error at the remote station causing it to reset.

ACTION: See message #226 for details of the connection data.

If this problem persists, contact support personnel for your network.


Message 230

Remote station not responding to value commands

Connection = value

Local MAC address = value

Local ring number = value

Remote MAC address = value

Routing data = value

Source SAP = value

Destination SAP = value

EXPLANATION: The remote station could not be contacted because it is not answering TEST or XID frames. This could be caused either by an incorrectly configured remote MAC address or remote SAP address, or by a fault in the intervening network (for example, a bridge fault).

ACTION: Check the configuration details, then contact support personnel for your network


Message 231

Configuration or installation error (value)

EXPLANATION: This error should not normally occur.

ACTION: Contact network support personnel, and supply the reported error code.


Message 232

Storage capacity exceeded

local MAC address = value

local ring number = value

EXPLANATION: The storage capacity of the DLC (802.2) link service has been exceeded. Frames have been rejected and the connection will stop receiving data. The connection will start receiving data again when some storage has been freed.

ACTION: No action is necessary.


Message 233

A DLC command failed, error code value

EXPLANATION: An error code which is not explicitly handled by SNA Server has been returned by the DLC driver.

This could be due to network card misconfiguration or hardware problems.

ACTION: Contact network support personnel, and supply the reported error code.


Message 234

Failed to open SAP value, error (value)

Some connections may now be unavailable

EXPLANATION: The DLC (802.2) link service failed to open a service access point (SAP) during initialization. If error code 43 is displayed, the SAP has already been opened by another link process.

ACTION: If other errors occur, contact network support personnel with the reported error code.


Message 235

All SAPs failed to open, no connection is usable

EXPLANATION: The DLC (802.2) link service failed to open any service access points (SAPs). This error can occur when two nodes have the same SAP addresses configured.

ACTION: Check that the DLC (802.2) link service is properly installed and that SAPs are available.


Message 236

DM or DISC received


Message 237

Protocol timer Ti has expired

EXPLANATION: Ti is an activity timer for DLC (802.2) traffic between two remote computers. When a server fails to receive a DLC (802.2) frame within the activity timer (Ti) from a remote computer with which it is communicating, the activity timer (Ti) elapses and this error message is logged. This may occur because the LAN is heavily loaded or because the remote computer has been turned off.

ACTION: Check that the remote computer is still functioning correctly. If the LAN is heavily used, the activity timer (Ti) may need to be reconfigured by changing your LAN operating system configuration.


Message 238

Connection value statistics

Station log IFTX IFRX ERTX ERRX T1EX
value

SAP log FRTX FRRX FDSC DLST NBUF
value

Adapter log LNER INER BTER ACER ABDL LFRM RXCG FCER FQER TKER
value

EXPLANATION: This message logs the LAN LLC statistics when a connection is terminated. This information is provided to help evaluate the performance of the LAN or isolate problems in the operation of the LAN. Descriptions of the fields are as follows:

Station log:

IFTX Number of I-frames transmitted

IFRX Number of I-frames received

ERTX Number of I-frames transmitted with an error resulting

ERRX Number of I-frames received with an error resulting

T1EX Number of times T1 timer expired

SAP log:

FRTX Number of frames transmitted

FRRX Number of frames received

FDSC Number of frames discarded

DLST Number of times data lost

NBUF Number of buffers available in buffer pool

Adapter log:

LNER Number of line errors

INER Number of internal errors

BTER Number of burst errors

ACER Number of A/C errors

ABDL Number of times abort delimiter transmitted

LFRM Number of lost frames

RXCG Number of times receiver congested

FCER Number of frame copied errors

FQER Number of frequency errors

TKER Number of token errors

ACTION: Refer to the IBM Token Ring Network Architecture Reference for descriptions and explanations of the fields. No action is necessary.


Message 239

Adapter initialized successfully

EXPLANATION: The adapter initialization is complete with no errors.

ACTION: No action is necessary.


Message 240

Connection value started

EXPLANATION: The DLC (802.2) connection shown has been started.

ACTION: No action is necessary.


Message 241

Connection value stopped

EXPLANATION: The DLC (802.2) connection shown has been stopped.

ACTION: No action is necessary.


Message 242

Invalid adapter value configured

EXPLANATION: The DLC (802.2) link service is configured to use an NDIS adapter that is not installed.

ACTION: Refer to the installation manual for details on installing the DLC drivers. Check that the setting of the adapter (primary or secondary) corresponds to the link service configuration.


Message 243

Permanent error occurred during initialization (subcode value)

EXPLANATION: A permanent error occurred while the DLC (802.2) link service attempted to initialize the adapter. This error should not normally occur.

ACTION: Provide network support personnel with the reported subcode.


Message 244

DLC Protocol service has not been started

EXPLANATION: The DLC.SYS process is not running.

ACTION: Refer to the Windows NT installation manual for details on installing the DLC driver.


Message 246

Terminating unused DLC (802.2) service

EXPLANATION: No connections are configured to use this DLC (802.2) link service, so it has terminated.

ACTION: No action is necessary.


Message 247

DLC (802.2) link service value not configured in value

EXPLANATION: The operator attempted to start an SNA Server DLC (802.2) link service but supplied a service name that was not in the configuration file.

ACTION: Start the link service with the correct link service name from the configuration file.


Message 248

Incorrect parameters on starting DLC (802.2) link service

EXPLANATION: This is an internal error that should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and a trace file for the DLC (802.2) link service. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 249

An error occurred when accessing the DLC Protocol service.

EXPLANATION: The DLCAPI.DLL file either does not exist or is corrupt. This error can occur if you attempt to start a primary, backup, or member server on a computer that is only set up to be a client.


Message 251

No Connection for Message

EXPLANATION: SNA Server received a message from the host, but the link service does not have a node connection for the message. This error should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and a trace file for the DFT link service. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 252

Error during initialization, rc = value

EXPLANATION: An error was returned from a Windows NT function during an attempt to initialize the DFT connection.

ACTION: See your Windows NT documentation for information on return codes. Check the return code. Check that the device name of the DFT driver specified in the link service dialog matches the name specified in the Registry. If the problem persists, contact network support personnel.


Message 253

Connection Activation Failed, rc = value

EXPLANATION: This error is caused by failure of the first DFT driver initialization message. The return code from the DeviceIoControl call is shown on the screen.

ACTION: See your Windows NT documentation for information on return codes. Check the return code and the hardware configuration. If the problem persists, contact network support personnel.


Message 254

Unknown Internal Message

EXPLANATION: An SNA Server internal message is received but not recognized. This error should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and SNA Server trace file(s), including Data Link Control traces for the server. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 255

Buffer Shortage

EXPLANATION: There are insufficient buffers for the component to continue processing.

ACTION: Use the COMBUF Registry variable to allocate more buffers to the component.

If increasing the size of the buffer pool does not solve the problem, an internal error may be occurring. Provide network support personnel with the event log file(s) related to SNA Server, SNA Server trace file(s) such as Data Link Control traces of the server or the affected link service, and the dump file.

For information about SNA Server log, trace, and dump files, see the Microsoft SNA Server Administration Guide. For information about COMBUF, see Appendix C, "Registry and Environment Variables for SNA Server."


Message 256

Lost Connection

EXPLANATION: The connection to the server (node) is lost. Possible causes are the failure of the node process, or the stopping of the node by an administrator.

ACTION: If the node failed, check other messages logged to indicate this failure, follow any action specified for them, and then retry.


Message 257

Bad Enqueue Type

EXPLANATION: This is an internal error and should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the dump file. For information about SNA Server log and dump files, see the Microsoft SNA Server Administration Guide.


Message 258

Station Contacted

EXPLANATION: The host is communicating with the control unit.

ACTION: No action is necessary.


Message 259

Unexpected Message on PU Session: value value value value value value

EXPLANATION: An unexpected message was received on the SSCP-to-PU session indicating an internal error in SNA Server. The text of the received message is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and one or more SNA Server trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 260

Open Link/Station Failed

EXPLANATION: There has been a failure to open the link adapter. This error should not occur during normal operation.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and one or more SNA Server trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 261

Line Check (value) on adapter value. Its LUs will be unavailable.

EXPLANATION: The DFT link service detected a line check. The line check value shown corresponds to one of the Operator Information Area (OIA) indicators that appear in the status line of a 3270 emulator.

ACTION: Look up the OIA indicator in the 3270 Applet online help.


Message 263

The controller has reported a non-productive receive timeout

Your host system may have gone down

EXPLANATION: The DFT controller has not received anything from the host for some time. The connection may have been lost with the host. If the connection has been lost, eventually the controller will report it as failed. It is possible that the connection has not been lost if the host is very slow at polling its remote nodes. The values for these timeouts are configured on the controller.

ACTION: If this message persists, contact your host administrator.


Message 264

The controller has reported a machine check (value) on adapter value

Refer to the controller diagnostics manual for more information

EXPLANATION: The DFT link service reported a machine check, indicating a serious problem in the controller.

ACTION: Check the machine check number in the controller diagnostics manual, and take the recommended action.


Message 265

The controller is not SNA attached

EXPLANATION: The DFT link service detected that it is attached to a non-SNA controller. SNA Server does not support non-SNA controllers. The connection is not activated and it remains in the Pending state.

ACTION: Stop the link service, attach the DFT link service to an SNA controller, and then restart the link service.


Message 297

DFT link service value not configured in value

EXPLANATION: The service name entered while starting an SNA Server DFT link service is not in the configuration file.

ACTION: Start the link service with the correct link service name as it appears in the configuration file.


Message 298

Incorrect parameters on starting the DFT link service

EXPLANATION: This is an internal error that should not occur during normal operation.

ACTION: Contact network support personnel.


Message 300

(value) Internal Error

EXPLANATION: SNA Server detected an invalid message between different layers of the X.25 link service protocol stack (identified here as L2, L3, and QLLC). This is an internal logic error and should not occur during normal operation.

SUBCODE INFORMATION:

X'2540' L2 received illegal reset request from L3.

X'2541' L2 received illegal reset confirm from L3.

X'2542' L2 received illegal restart request from L3.

X'2543' L2 received illegal restart confirm from L3.

X'2544' L2 received illegal data packet from L3.

X'2545' L2 received illegal call request from L3.

X'2546' L2 received illegal call accept from L3.

X'2547' L2 received illegal clear request from L3.

X'2548' L2 received illegal clear confirm from L3.

X'2549' L2 received unidentified packet from L3.

X'25AF' L3 received illegal reset request from QLLC.

X'25B0' L3 received illegal reset confirm from QLLC.

X'25B2' L3 received illegal restart request from QLLC.

X'25B3' L3 received illegal call request from QLLC.

X'25B4' L3 received illegal call accept from QLLC.

X'25B5' L3 received illegal clear request from QLLC.

X'25B6' L3 received illegal clear confirm from QLLC.

X'25B7' L3 received unidentified packet from QLLC.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server and the dump file. For information about SNA Server log and dump files, see the Microsoft SNA Server Administration Guide.


Message 301

(value) Network Packet Sequence Error

EXPLANATION: The node received an unexpected message from the X.25 network.

SUBCODE INFORMATION:

X'2512' A Clear or Reset confirm was received in an invalid state.

X'2513' A call indication was received in an invalid state.

X'2514' A Call Accept was received in an invalid state

ACTION: Provide network support personnel with the number and description of the displayed subcode.


Message 302

(value) Failed to initiate outgoing call

EXPLANATION: An outgoing call could not be established.

Note This condition may occur if connections are started while the X.25 service is still initializing its connection to the X.25 network.

SUBCODE INFORMATION:

X'2510' An outgoing call could not be established due to a network failure.

ACTION: Check the above conditions, then retry.


Message 303

(value) Resource Allocation Error

EXPLANATION: This is an internal error and should not occur during normal operation.

SUBCODE INFORMATION:

X'2505' L3 clock handler has run out of QCBs.

X'2506' Run out of QCBs on clock initialization.

X'2521' Buffer manager cannot allocate a QCB.

X'2522' Buffer manager cannot provide an RX buffer.

X'2523' Buffer manager cannot release an RX buffer.

X'2524' Buffer manager cannot release a TX buffer.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, the SNA Server configuration file, and the number and description of the displayed subcode. For information about SNA Server log files and the configuration file, see the Microsoft SNA Server Administration Guide.


Message 304

(value) Initialization Failure

EXPLANATION: This internal error should not occur during normal operation.

SUBCODE INFORMATION:

X'2500' Failed to initialize the X.25 RECEIVE handler.

X'2501' Failed to initialize the X.25 TRANSMIT handler.

X'2502' Failed to initialize the X.25 L3 handler.

X'2503' Failed to initialize the X.25 L3 clock handler.

X'2504' Failed to initialize the X.25 L2 clock handler.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 305

(value) Initialization Failure: configuration error

EXPLANATION: This is an internal error in SNA Server (but it may be caused by a corrupted configuration file).

SUBCODE INFORMATION:

X'250D' Failure in configuration initialization.

X'250E' Failure to access a configuration record.

ACTION: Check that the configuration file can be opened using SNA Server Manager, and that the X.25 link service configuration appears to be correct. If it does, provide network support personnel with the event log file(s) related to SNA Server, and the SNA Server configuration file. For information about SNA Server log files and the configuration file, see the Microsoft SNA Server Administration Guide.


Message 306

(value) Unexpected request from node service

EXPLANATION: Severity 12.

SUBCODE INFORMATION:

X'250F' This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 308

EICON call/listen failed to connect (rc = value)


Message 309

Error returned from EICON toolkit (value)


Message 310

(value) Illegal packet received from network

EXPLANATION: An unexpected or invalid packet was received from the network.

SUBCODE INFORMATION:

X'2511' Unrecognized qualified data packet.

X'2555' Illegal Reset Indication packet.

X'2556' Illegal Reset Confirm packet.

X'2557' Illegal Restart Indication packet.

X'2558' Illegal Incoming Call packet.

X'2559' Illegal Call Connected packet.

X'255A' Illegal Clear Indication packet.

X'255B' Illegal Clear Confirm packet.

X'255C' Unrecognized packet type.

X'255E' Received an unexpected or invalid packet on a PVC.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server and SNA Server trace file(s) such as Data Link Control trace files for the server. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 311

INTERRUPT packet (invalid for SNA) received on connection value.

EXPLANATION: An INTERRUPT packet has been received over an X.25 connection. This results in a link outage being created and the connection being brought down.

ACTION: Contact support services at your site if this problem persists.


Message 312

Data received on connection value before QLLC in information transfer

EXPLANATION: X.25 NORMAL data (with the Q bit clear) has been received over a Virtual Circuit (VC) before a QLLC connection has been activated.

ACTION: Retry the procedure; if it continues to fail, contact support services.


Message 313

QLLC contact procedures for connection value have timed out

EXPLANATION: A link time-out has occurred while trying to establish a QLLC connection over X.25.

ACTION: Retry the procedure; if it continues to fail, contact support services.


Message 314

EICON initialization failed


Message 315

The port for this link service is not valid


Message 319

Call Cleared due to local buffer shortage

EXPLANATION: Abandoned an attempt to initiate a call because of a buffer shortage.

ACTION: Retry the operation that initiated the connection.


Message 320

Device driver value error on function value, rc = value

EXPLANATION: An internal error has been reported by the X.25 device driver.

ACTION: Provide support services at your site with details of the function number and return code shown on this message.


Message 321

Open failed for device driver value. Windows NT rc = value

EXPLANATION: An attempt to open the X.25 device driver caused an error. The return code from the OpenFile call is shown.

ACTION: See your Windows NT documentation for information on return codes. Check the return code. This probably indicates that the driver is not installed or is already in use.


Message 322

Driver value DSR is OFF at initialization

EXPLANATION: The DSR signal from the modem has not come up, which indicates that the modem is not functioning correctly.

ACTION: Check the modem connections and make sure the modem is functioning correctly. See the Microsoft SNA Server Administration Guide for more information.


Message 324

Driver value DSR has come ON

EXPLANATION: The DSR signal from the modem has come up. This message follows message #322 or #325 when the modem becomes operational.

ACTION: No action is necessary.


Message 325

Driver value DSR has gone OFF: probable modem failure

EXPLANATION: The DSR signal from the modem has gone down during communications, which indicates that the modem is not functioning correctly.

ACTION: Check the modem connections and functions. See the Microsoft SNA Server Administration Guide for more information.


Message 326

Driver value unable to use DMA

EXPLANATION: SNA Server cannot use Direct Memory Access (DMA) for this driver either because the adapter card does not support DMA or DMA is already being used on another card. SNA Server will operate with the driver in character interrupt mode. This could affect performance.

ACTION: No action is necessary.


Message 327

Switched Virtual Circuit established for connection value

EXPLANATION: A Call Connected packet has been received from the network in response to a Call request for the indicated connection.

ACTION: No action is necessary.


Message 328

Virtual Circuit lost for connection value

EXPLANATION: An X.25 virtual circuit for connection conname has ended. If the connection failed, this message is accompanied by other messages indicating the reason for the failure.


Message 329

Outgoing Call Request has been timed out.

Check that the configured channel ranges are valid.

EXPLANATION: An attempt to initiate a connection over a switched virtual circuit has timed out. A common reason for this is that the channel number ranges for the X.25 link service were configured incorrectly.


Message 331

Invalid packet received (header = value)

Channel number = value

Packet type = value

EXPLANATION: A packet has been received with an invalid header format or channel number. The packet header is displayed (3 bytes shown in hexadecimal), along with the channel number (decimal) extracted from the header, and the packet type identifier (hexadecimal) with protocol information removed.


Message 332

RESTART packet received from network.

Cause = value

Diagnostic = value

EXPLANATION: A RESTART packet has been received from the X.25 network. All virtual circuits are cleared and reset, and any active connections will be lost. The displayed Cause and Diagnostic are the cause and diagnostic fields (shown in decimal) from the RESTART packet.

A RESTART packet is normal whenever communication between the X.25 link service and the X.25 network is first established.


Message 333

CLEAR packet received from network on channel value

Cause = value

Diagnostic = value

EXPLANATION: A CLEAR packet has been received from the X.25 network. The connection using the indicated channel of the switched virtual circuit is broken. The displayed Cause and Diagnostic are the cause and diagnostic fields (shown in decimal) from the CLEAR packet.

A CLEAR may also be the response to a CALL packet indicating that the switched virtual circuit could not be completed. A cause code value of zero indicates that the CLEAR originated from the host.


Message 334

RESET packet received from network on channel value

Cause = value

Diagnostic = value

EXPLANATION: A RESET packet has been received from the X.25 network. The connection using the indicated channel of the switched virtual circuit is broken. The displayed Cause and Diagnostic are the cause and diagnostic fields (shown in decimal) from the RESET packet.

A value of zero for the Diagnostic indicates that the RESET originated from the host.

ACTION: If the RESET was unexpected, restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 335

Incoming CALL packet received on channel value

Remote (calling) NUA = value

Local (called) NUA = value

Facility data = value

EXPLANATION: An incoming CALL packet indicates that a remote computer is attempting to establish an X.25 connection with a local server. This will be rejected unless an active local server has been configured to receive incoming calls to address locNUA and has an X.25 connection configured with address remNUA.

The "Facility data" is a hexadecimal representation of the facility data on the CALL packet. If the requested facilities are invalid or not supported by the X.25 link service, the CALL is rejected.

No action is necessary.


Message 336

CALL CONNECTED response received on channel value

Remote (called) NUA = value

Local (calling) NUA = value

Facility data = value

EXPLANATION: A switched virtual circuit has been connected successfully on the specified channel. This packet is an "OK" response to a previous CALL request packet sent by the X.25 link service.

The returned facility data is displayed in hexadecimal. The values may have been negotiated (altered) by either the remote host or the X.25 network itself.

Note The locNUA may be filled in by the X.25 network itself, even if it has not been configured and was not present on the initial CALL packet.

No action is necessary.


Message 337

RESTART packet sent. Diagnostic = value

EXPLANATION: The X.25 link service has sent a RESTART request to the X.25 network. Any active connections are lost.

A RESTART packet is normal whenever communication between the X.25 link service and the X.25 network is first established, but otherwise may indicate that a serious failure has occurred.

ACTION: If the RESTART was unexpected, restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 338

CLEAR packet sent on channel value. Diagnostic = value

EXPLANATION: The X.25 link service has sent a CLEAR request to the X.25 network, breaking the switched virtual circuit on the indicated channel.

A diagnostic code of zero is sent when the virtual circuit is being cleared because the connection using it is no longer active. Non-zero values are sent when the X.25 link service detects an incorrect or unexpected packet from the host or the X.25 network.

ACTION: If the CLEAR was unexpected, restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 339

RESET packet sent on channel value. Diagnostic = value

EXPLANATION: The X.25 link service has sent a RESET request to the X.25 network on the indicated permanent virtual circuit channel. The connection using the circuit was lost.

A diagnostic code of zero is sent when the virtual circuit is being reset because the connection using it is no longer active. Non-zero values are sent when the X.25 link service detects an incorrect or unexpected packet from the host or the X.25 network.

ACTION: If the RESET was unexpected, restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 340

Outgoing CALL packet sent to NUA value on channel value

Local (calling) NUA = value

Facility data = value

User data = value

EXPLANATION: This is a log of the CALL packet sent when attempting to initiate a connection to the host configured with NUA remNUA. The X.25 link service used the first available channel (channel number indicated) on which to send the CALL. Any subsequent CLEAR should be received on the same channel. No action is necessary.


Message 341

CALL ACCEPTED response sent on channel value

Facility data = value

EXPLANATION: An incoming CALL on the indicated channel number has been accepted. The facility data values may have been negotiated (altered) by the X.25 link service. No action is necessary.


Message 342

Unexpected packet type (value) received on connection value

EXPLANATION: The indicated connection has been lost. The "packet type" value is the packet type identifier field (hexadecimal) with protocol information removed from the erroneous packet's header.

ACTION: Restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 343

Unexpected QLLC control field (value) received on connection value

EXPLANATION: The indicated connection has been lost. The "control field" value is a hexadecimal representation of the QLLC (qualified logical link control) control field from the packet causing the problem. QLLC is one of the protocols commonly used for transporting SNA data over X.25 virtual circuits.

ACTION: Restart the link service with tracing on, and try to reproduce the error. Contact the host administrator if the problem occurs again.


Message 344

Invalid QLLC control field (value) received on connection value

EXPLANATION: A packet has been received from the X.25 network which has the Q bit set, but does not contain a valid QLLC command.

ACTION: Contact support services.


Message 345

Invalid QLLC i-field (cfld value, len value) on connection value

EXPLANATION: A recognized QLLC packet has been received from the X.25 network, but the packet has an illegal i-field (data) attached.

ACTION: Contact support services for the service being accessed.


Message 346

Q Frame Reject received on connection value: info = value

EXPLANATION: A Frame Reject from the X.25 network has been received.

ACTION: No action is necessary.


Message 347

X.25 link service value not configured in value

EXPLANATION: An attempt was made to start an SNA Server X.25 link service with a service name that is not in the configuration file.

ACTION: Use SNAX25.DLL with the link service name used in the configuration file.


Message 348

Incorrect parameters on starting X.25 link service

EXPLANATION: This is an internal error that should not occur during normal operation.

ACTION: Contact support services at your site.


Message 350

Run out of memory

EXPLANATION: The SNA Server component that logged this message is unable to continue due to a memory shortage.

ACTION: If you continue the file transfer process, the system may or may not complete the procedure. If possible, stop any programs that are unnecessary, and then retry.


Message 351

Error trying to read from value (rc = value)

EXPLANATION: A Windows NT error occurred during an attempt to read configuration information from the file shown for the component that logged this message.

ACTION: Check the Windows NT return code shown on this message. See your Windows NT documentation for information on return codes.


Message 352

Unable to open the configuration file, rc = value

EXPLANATION: A Windows NT error occurred while attempting to open the configuration file to obtain configuration information for the component that logged this message.

This error could be due to one of the following:

  • You have not configured the server using SNA Server Manager
  • The configuration file is corrupt
  • This is a member server and the primary/backup servers are not available

ACTION: Check the Windows NT return code shown on this message. See your Windows NT documentation for information on return codes.


Message 353

Link service record for value in value is too short

EXPLANATION: The configuration file information on a link service is invalid, indicating an internal error in the configuration program.

ACTION: Provide network support personnel with a copy of the SNA Server configuration file. For information about the configuration file, see the Microsoft SNA Server Administration Guide.


Message 360

(value) Unexpected error logged

EXPLANATION: An internal error. An SNA Server component has used an internal message that does not appear in SNA Server. Although logged at level 12 to ensure that it is not ignored, this does not necessarily indicate a level 12 problem.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, internal trace file(s), and any information displayed in this message. For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 361

Failed to open help file value, rc = value

EXPLANATION: The help file shown could not be opened. The return codes generated are listed here.

SUBCODE INFORMATION:

OpenFileOnPath failed. Check that the file exists in a directory in the PATH environment variable, and that you have permission to access the file.

Could not read file header. The help file may have been corrupted.

Too many open help files. This error should not occur during normal use. Contact support services at your site.

Bad appended file. This error should not occur during normal use. Contact support services at your site.

The file accessed was not a help file. You may have copied another file to this file by mistake.

Incompatible version. The version of the help file is incompatible with the version of the program you are using. Make sure you are using the help file that was provided with the program.

Memory allocation failed. There was not enough memory available to open the help file. Try to clear more memory and then retry.

ACTION: Check the return code and take the indicated action.


Message 362

Could not find help ID value in help file value

EXPLANATION: This is an internal error. The help text for a particular dialog or menu item could not be found in the help file.

ACTION: Make a note of the help ID and file name reported on this message, and contact support services at your site.


Message 390

The following alert was sent on session value

Title: value

EXPLANATION: A 3270 user sent a NetView user alert via a 3270 emulator. The title of the user alert is shown, along with any user-supplied parameters. No action is necessary.

NetView user alerts are configured using the NetView command from the Options menu in SNA Server Manager.


Message 391

value: value value


Message 392

Warning: User Alert was not accepted by the host

EXPLANATION: A 3270 user sent a user alert, but the host sent a negative response. Either the host does not accept this particular alert number or the NetView program is not running at the host.

ACTION: Check with the host administrator to determine whether the alert is invalid or NetView is not running.


Message 393

Audit message logged by value : value


Message 394

Error message logged by value : value


Message 397

Cannot support any further client applications


Message 540

NMVT type value logged by value, data:

value

EXPLANATION: An alert is logged by an SNA Server component to indicate an error condition, or by an application program using the TRANSFER_MS_DATA verb.

ACTION: See Chapter 2, "Network Management," for explanations of alert formats.


Message 543

Can't switch focus: background thread has not terminated


Message 544

The connection to the network has been established.


Message 545

This type of SnaBase service must run on a system which is not sharing COMCFG


Message 546

Cannot establish connection with sponsor box value.


Message 547

The connection to the sponsor box value has been lost.


Message 548

The SnaBase service was already started in another MS-DOS session


Message 549

Cannot start SNA Server Manager on remote client.


Message 550

Previous attempts to log failed, value messages lost


Message 551

Memory allocation failure, rc = value

EXPLANATION: A resource error occurred during initialization. The return code from GlobalAlloc is shown.

ACTION: Check the return code. Check that there is enough memory for the new process.


Message 552

Failed to create receive thread, rc = value

EXPLANATION: A CreateThread call has failed. The return code is shown.

ACTION: Check the return code. Provide support services at your site with the log file and return code.


Message 553

Could not create mailslot, rc = value

EXPLANATION: A CreateMailslot call failed. The return code is shown.

ACTION: Check the return code. Provide support services at your site with the log files.


Message 554

Unknown OPEN, type = value

EXPLANATION: This is an internal error. An application supplied an invalid OPEN message.

ACTION: Provide support services at your site with the log files.


Message 555

Local routing table full: too many clients using the service

EXPLANATION: The system is limited to 1024 processes using any one service. This limit should not be reached in normal operation.

ACTION: Contact support services at your site.


Message 556

A system error occurred while making a pipe connection, rc = value

EXPLANATION: An internal error occurred during an attempt to open a connection.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 557

DLOAD has timed out

EXPLANATION: The node requested dynamic loading of an APPC TP, but did not receive a response from the TP within the specified time. This could be caused by the following conditions:

  • The TP started but failed before issuing a Receive_Allocate (check for messages logged by the TP).
  • The "Timeout for Starting TPs" for the local APPC LU used by this TP is too short.
  • The TP is operator-started, and the operator did not start it.


Message 558

Could not create service table semaphore, rc = value

EXPLANATION: A CreateSemaphore call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 559

The SnaBase service is already active

EXPLANATION: An attempt was made to start the SnaBase after it was already running. Each computer can run only one copy of the SnaBase at a time.

ACTION: No action is necessary.


Message 560

Read from mailslot failed, rc = value

EXPLANATION: A ReadFile call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 561

Write to mailslot failed, rc = value

EXPLANATION: A WriteFile call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 562

Failed to obtain workstation information, rc = value

EXPLANATION: A NetWkstaGetInfo call failed. The return code is shown.

ACTION: Check that the workstation service has been started. Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 563

The service table is full: too many network resources active

EXPLANATION: The system limit of 254 active services is reached and another service cannot be activated.

ACTION: Remove any services that are no longer required. Contact support services at your site.


Message 564

Failed to initialize exit list processing, rc = value

EXPLANATION: A DosExitList call on an OS/2-based client failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 565

Failed to access shared memory, rc = value

EXPLANATION: A CreateFileMapping call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 566

Write to a named pipe failed, rc = value

EXPLANATION: A WriteFile call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 567

Creation of a named pipe failed, rc = value, pipe = value

EXPLANATION: A CreateFile call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 568

Failed to associate pipe with semaphore, rc = value

EXPLANATION: A DosSetNmPipeSem call on an OS/2-based client failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 569

Error when querying pipe semaphore, rc = value

EXPLANATION: A DosQNmPipeSemState call on an OS/2-based client failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 570

Dynamic load failed

EXPLANATION: The node requested dynamic loading of an APPC TP but the TP cannot be started. This message is usually accompanied by message #575, giving the TP name and the reason for failure.

ACTION: See the accompanying message (#575).


Message 571

Unable to read from Named Pipe, rc = value

EXPLANATION: An Asynchronous read on a connection failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 572

Premature timeout of a DLOAD request

EXPLANATION: Received a response to a dynamic load request that already timed out. The invokable TP was not started within the specified time, so the request has been canceled.

ACTION: The timeout may be too short — try increasing it.


Message 573

Process has ended abnormally

EXPLANATION: A service or a client ended abnormally due to an exception condition. There may be other messages preceding this one that indicate the nature of the error. Also, a dump file was created. A message with number 624 gives the name of the dump file.

ACTION: Check other messages.


Message 574

Unexpected message type value

EXPLANATION: This is an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and internal trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 575

Failed to execute a program, rc = value, name = value

EXPLANATION: A CreateProcess call for a dynamically loaded TP failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 576

No more DLOAD queue entries available

EXPLANATION: A TP reached the limit of 256 queued allocates. The TP cannot process requests quickly enough to keep up with the requests coming in.

ACTION: If possible, speed up the processing of the TP (for example, it may be slow due to memory shortage), or redistribute the load by setting up another TP.


Message 577

Dynamic load request received for non-existent TP

EXPLANATION: This is an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 578

SnaBase service cannot be run on an SNA Server 1-User system

EXPLANATION: You attempted to start the SNA Server SnaBase service, but SNA Server 1-User components were already running. SNA Server and SNA Server 1-User cannot run on the same computer.

ACTION: Stop the SNA Server 1-User components before trying to start the SNA Server SnaBase service.


Message 579

Source and dest incompatibility, msg = value,value, parms = value,value

EXPLANATION: This is an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and internal trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 580

Sending a message to inactive destination id value

EXPLANATION: A message is routed to an inactive process. This is generally caused by abnormal termination of an SNA Server component.

ACTION: Check for previous messages indicating abnormal termination. Follow the actions suggested for them.


Message 581

3270 Emulation (value) started

EXPLANATION: This message is for informational purposes.

No action is necessary.


Message 582

No name supplied in the parameter list for this component

EXPLANATION: SNA Server started the component without supplying a name. This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 583

Failed to address a buffer pool, rc = value

EXPLANATION: A CreateFileMapping call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 584

Routing table entry value is no longer required

EXPLANATION: This message indicates that an internal routing table entry between components is no longer required because the association between the components has ended (for example, the end of a conversation).

ACTION: No action is necessary.


Message 585

Please load TP: value

Program: value

Parameters: value

Time limit: value seconds

EXPLANATION: This is a request to load an operator-started TP.

ACTION: Load the program shown using the parameters listed.


Message 586

The workstation service must be started before the SnaBase service can be started

ACTION: Use the NET START WORKSTATION command (for a client) or NET START SERVER (for a server) before starting the SnaBase service. Or use the Windows NT Control Panel to start the appropriate services in order. For a client, start the workstation service, and then the SnaBase service. For a server, start the workstation service, then the Server service, and then the SnaBase service.


Message 587

Message did not have value elements as indicated in the header

EXPLANATION: This is an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and internal trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 588

Failed to add SnaBase exit list, rc = value

EXPLANATION: A DosExitList call failed. The return code is shown.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and the return code included in this message. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 589

Failed to display a pop-up, rc = value

EXPLANATION: A CreateProcess call for the pop-up process failed. The return code is shown.

ACTION: Check the return code and attempt to free more memory. A return code of 999 indicates that a pop-up could not be displayed on an MS-DOS-based system because an application was already using the foreground screen.

This error is caused by a resource shortage on the system.

Also, provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 590

This service terminated by administrator

EXPLANATION: The process was terminated by the administrator, using either SNA Server Manager or the SNA Server command-line interface.

ACTION: No action is necessary.


Message 591

TP has not been configured

EXPLANATION: A TP issued the RECEIVE_ALLOCATE verb with a TP name that is not known to the system.

ACTION: Check the TP name against the configuration. The TP should supply a name that matches the Full TP Name field in an Invokable TP record. For information about TPs, see the Microsoft SNA Server APPC Programmer's Guide or the Microsoft SNA Server CPI-C Programmer's Guide.


Message 592

Receive Allocate has timed out

EXPLANATION: Receive_Allocate timed out. No incoming allocate was accepted within the configured timeout period.

ACTION: Increase the configured timeout period if the timeout was not due to an error. This timeout is specified for the local APPC LU in the APPC LU Properties dialog box of SNA Server Manager.


Message 593

Too many routing entries attempted

EXPLANATION: This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 594

DLOAD free queue contention is relieved

EXPLANATION: The SNA subsystem succeeded in queuing an ALLOCATE request to the TP. This means that the condition indicated by the previous message #576 (no more DLOAD queue entries available) cleared. This is not an error condition, but is logged at the same level as

#576 to ensure that both messages will appear.

ACTION: Refer to message #576.


Message 595

Buffer pool has been extended to value kilobytes

EXPLANATION: The buffer pool emptied and had to be extended. This condition is caused by heavy usage of the node. If it occurs too frequently it may cause performance problems. The pool size will be increased in increments of 16 K until it reaches 128 K.

ACTION: The 128 K limit can be increased by using the COMBUF Registry variable. For information about COMBUF, see Appendix C, "Registry and Environment Variables for SNA Server."


Message 596

Attempt to start duplicate service value

EXPLANATION: An attempt was made to start a network service when a service of the same name is already started. The service name must be unique.

ACTION: Use unique service names.


Message 597

User limit of value exceeded: client connection rejected

EXPLANATION: The maximum number of licensed users (shown) has been reached and another cannot be added.

ACTION: Purchase additional licenses and increase the user count using the Control Panel Licensing dialog.


Message 598

No LAN user ID found: perform NET LOGON

EXPLANATION: A user attempted to start the SnaBase service on a client without first logging on to the LAN.

ACTION: Use the NET LOGON command to log on to the LAN, then restart the SnaBase service.


Message 599

Routing error on RAM pipe

EXPLANATION: This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 600

Open pipe failed as all available manage connections are in use


Message 601

Open pipe failed as all available pipes are in use


Message 602

value client executables already connected to value.

Unable to connect any more


Message 603

The queued transaction program is already started

EXPLANATION: You attempted to start a queued TP that had already been started. Only one copy of a queued TP may be run at a time. (Incoming [MC_]ALLOCATEs are queued until the program is available.)

ACTION: If multiple concurrent copies of the TP are required, it must be configured as non-queued.


Message 604

Bad client type value

EXPLANATION: A client has called the DMOD initialization for Windows (SBPWINIT) with an invalid client type.


Message 605

SNA Server version mismatch: Version value detected on type value mailslot from computer value


Message 606

SNA Server version mismatch: Version value client value initiating communication with server value


Message 607

SNA Server version mismatch: Client value opening connection to version value server value


Message 608

Configuration file version is value: expected 2.1


Message 609

No valid version record found in configuration file


Message 610

Not authorized to access pipes on server value

EXPLANATION: A user tried to access the server without having the necessary access permissions.

ACTION: If access to this server is required by a particular user, update the LAN access permissions.


Message 611

The following event log entry has been written:

value

EXPLANATION: The warning (level 12) or error (level 16) shown in this message has been logged.


Message 612

The following log entry could not be written:

value

Logging has been disabled

EXPLANATION: The event log entry could not be recorded in the event log.

ACTION: Adjust the parameters that control the length of time that entries are retained in the Windows NT Event Log, or the parameters that control the size of Windows NT Event Log. For more information, see your Microsoft Windows NT documentation.


Message 613

Invalid computername or type of SnaBase service

EXPLANATION: An attempt was made to start an invalid type of SNA Server software or client software for the specified computername. The possible types are as follows:

  • The primary server, on which the primary configuration file is stored. There can be only one primary server in a subdomain.
  • Backup server(s), on which extra copies of the latest configuration file should be stored. There can be more than one backup server in a subdomain.
  • Member servers, on which there is no SNA Server configuration file. There can be more than one member server in a subdomain.
  • Client computers, which run client software, not SNA Server software.

ACTION: To change the role of the server, use SNA Server Manager.


Message 614

Network Server service must be started before SnaBase can be started for an SNA Server

EXPLANATION: Before starting a primary, backup, or member server, the network Server service must be started.

ACTION: Use the NET START SERVER command before starting the SnaBase service for a primary, backup, or member server. Or use the Windows NT Control Panel to start the Server service before starting the SnaBase service.


Message 615

Invalid MS-DOS version

EXPLANATION: You attempted to start the SnaBase service on a computer running a version of MS-DOS before 3.2. MS-DOS version 3.2 or later is required for an MS-DOS-based client.

ACTION: Upgrade the operating system software.


Message 616

Failed to open configuration file value

EXPLANATION: SNA Server failed to open the specified configuration file. This is usually caused when you do not have permission to access the configuration file.

ACTION: Make sure access permissions are set up for your LAN operating environment and that you are logged on to the LAN with the correct user ID and password.


Message 617

Cannot have two nodes running on one server

EXPLANATION: You attempted to start two nodes on the same server. You cannot run two nodes on one server.


Message 618

Failed to access configuration file value, rc = value

EXPLANATION: The process cannot read the configuration file. The file name shown should be COM.CFG. If anything else appears here, it indicates an internal error. Normally the Windows NT return code is shown. However, three additional values can also be returned here:

612 No configuration file is available at present.

616 Failed to obtain name of configuration file.

618 Invalid or corrupted configuration file.

ACTION: Contact support services at your site. For return codes 616 and 618, check that the file COM.CFG exists in the SYSTEM\CONFIG subdirectory of the SNA Server root directory, and that it is a valid configuration file (try opening it using SNA Server Manager). If you still have a problem, contact support services at your site.


Message 619

Failed to open pipe for DLOAD error response

EXPLANATION: This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 620

System shutdown requested

EXPLANATION: A shutdown is requested when a new version of the system is installed. This message is logged when a shutdown request is received. All SNA Server processes are terminated. No action is necessary.


Message 621

Invalid parameter to SnaBase. Must be:

[\\servername1 [\\servername2]]


Message 622

No dump file available

ACTION: Remove the dump files that are no longer needed.


Message 623

Maximum SNA Server errors reached

EXPLANATION: This is an SNA Server internal error.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 624

Creating dump file value for value

EXPLANATION: A process (value) ended abnormally due to a protection violation or similar condition and a dump file value has been created that contains information about the state of the process at the time of the exception. Register information is contained in your Windows NT root directory in the file DRWTSN32.LOG.

ACTION: For more information on diagnostics, refer to the Microsoft SNA Server Administration Guide. Provide network support personnel with the event log file(s) related to SNA Server, the dump file, and the Dr. Watson log file.


Message 625

The SnaBase service must be running before anything else

EXPLANATION: You attempted to start an SNA Server process on a computer where the SnaBase service was not running.

ACTION: Start the SnaBase service before any other SNA Server process.


Message 626

Service started

EXPLANATION: The service shown in the message header started successfully.

ACTION: No action is necessary.


Message 627

Internal routing call failed

EXPLANATION: This is an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server. For information about SNA Server log files, see the Microsoft SNA Server Administration Guide.


Message 629

No SNA Server configuration broadcast received

A server must be available before you can use 3270 or APPC

EXPLANATION: You attempted to start an application when there is no SNA Server on the LAN or the SNA Server did not broadcast information before the application was started.


Message 630

Failed to get SNA Server path from base driver on an OS/2-based client.

ACTION: On the OS/2-based client, check that the device driver line for COMBASE.SYS is correct in the CONFIG.SYS file. This line should have been added by the installation program, and should have the following form:

DEVICE=C:\COMMSRV\DEV\COMBASE.SYS C:\COMMSRV

In this line, both instances of C:\ should be replaced by the actual path of the COMMSRV home directory.

For SNA Server 1-User, this line should be in the following form:

DEVICE=C:\COMMWS\DEV\COMBASE.SYS C:\COMMWS

In this line, both instances of C:\ should be replaced by the actual path of the COMMWS home directory.


Message 631

Invalid message received across the LAN

EXPLANATION: This is an internal error.

ACTION: Contact support services at your site.


Message 632

Error scanning CONFIG.SYS, rc = value

EXPLANATION: A Windows NT error occurred during a scan of the CONFIG.SYS file for driver information on starting the SnaBase.

ACTION: Check the Windows NT return code shown.


Message 633

The sharename COMCFG does not exist, or the SNA Server configuration file COM.CFG does not exist.

EXPLANATION: When a primary or backup server is started, it must be sharing the configuration file on a share called \\servername\COMCFG, where servername is the name of the server. This is checked by the SnaBase at startup.

A SnaBase started as a backup server will also check the file replication information and may log message #634 as well.


Message 634

The SnaBase for a backup SNA Server has been started on a system with no file replication active.

EXPLANATION: File replication is recommended for keeping a current copy of the configuration file on each backup server. These copies of the configuration file should always kept current, so that incorrect or divergent copies are never loaded or saved.


Message 635

Error: Primary SNA Server already running in value

EXPLANATION: You tried to start two primary servers in the subdomain. Only one server in the subdomain can be the primary server.

ACTION: Use the Setup program to change one of the primary servers to a backup or member server.


Message 636

An SNA Server (node) can be started only if SNA Server software (primary, backup, or member) has been installed.

EXPLANATION: The server (node) cannot be started if the installed SnaBase is for clients.

ACTION: Start the server (node) on a computer on which the software for a primary, member, or backup server has been installed.


Message 637

There is no driver in CONFIG.SYS to support link service value

EXPLANATION: You tried to start a link service using a device driver that is not loaded.

ACTION: Do one of the following:

  • Load the device driver using the DEVICE= statement from the command line.
  • Upgrade CONFIG.SYS to include the DEVICE= statement for the device driver, and then reboot the PC.


Message 638

Possible Replication problem: the primary SNA Server was started on a system with file replication active but not replicating the SNA configuration file.

EXPLANATION: Check to see if this computer is supposed to support replication of SNA Server files. If not, ignore the message. If SNA Server file replication is intended, set up file replication with Windows NT.

ACTION: For information about setting up file replication, see your Windows NT documentation.


Message 639

Failed to open pipe to service value, rc = value

EXPLANATION: This message can be produced by any of the SNA Server components: 3270, APPC, or link services. The return code is either from the LAN or from Windows NT.

ACTION: Refer to your LAN or Windows NT documentation for explanations of the return codes, and then take the recommended actions.


Message 643

Invokable TPs can only be executed in the background when LAN Manager local security is active

EXPLANATION: You can execute invokable TPs only in the background when local security is active on the network. This message only applies to OS/2-based clients.

ACTION: Reconfigure the TP to run without a screen group, if it can run in that mode. Otherwise, load the TP on a server that is not running local security.


Message 644

Failed to open the primary trace file value, rc = value

EXPLANATION: There was a problem opening the primary trace file. The name may have been entered incorrectly.

ACTION: Check the Windows NT return code shown on this message. See your Windows NT documentation for more information on return codes and take the recommended action.


Message 645

Failed to open the secondary trace file value, rc = value

Tracing will proceed to the primary file without flip-flop

EXPLANATION: There was a problem opening the secondary trace file. Tracing will continue using the primary trace file.

ACTION: Check the Windows NT return code shown on this message. See your Windows NT documentation for information on return codes and take the recommended action.


Message 646

Failed to access configuration file value on this server, rc = value

EXPLANATION: This server is configured as a primary or backup server but a local SNA Server component has failed to open COM.CFG.

ACTION: Check access permissions and make sure the file exists.


Message 647

SNA Server could not initiate LAN communications due to a LAN connection failure.

EXPLANATION: The first mailslot broadcast issued a return code 2136 — NERR_NetworkError. This means that although the primary or backup server (node) started, the LAN is down. Any services started on the server cannot communicate with clients or with other nodes, but you can work locally on the server.

ACTION: Contact the LAN administrator at your site to get the LAN working.


Message 648

Connection to client computer value taken down: too much data queued to the client.

EXPLANATION: A server-client connection to an MS-DOS-based client or Windows-based client has been lost because the client has been switched out for a considerable amount of time and the server has run out of space for queuing the data it needs to send to the client.

ACTION: Contact support personnel at your site.


Message 649

Unable to create another connection: reached limit on number of processes.


Message 650

ConnectNmPipe returned error rc = value.


Message 651

Failed to load value

EXPLANATION: The COMM START command failed because the file shown cannot be loaded. If the file is listed with an extension of .EXE, the file is executable. If the file is listed with no extension, it is a .DLL file.

ACTION: Check to see that the file exists and that the PATH environment variable for an executable file, or LIBPATH for a .DLL file, is set up to point to the directory containing the file. Also, make certain that there is enough memory to load the executable files.


Message 652

value is already started

EXPLANATION: Service specified by the COMM START command is already started. No action is necessary.


Message 653

value is not a valid service name

EXPLANATION: The service name supplied to COMM START was not found in the configuration file.

ACTION: Check the correct name in the configuration file and retry COMM START.


Message 654

value failed to start in the allowed time. Check the event log.

EXPLANATION: An attempt to start the service failed.

ACTION: Check the event log files for other messages indicating the reasons for the failure, and take the recommended action(s).


Message 655

value has not been started

EXPLANATION: The COMM STOP command for the service is ignored because the service is not started.

ACTION: No action is necessary. Use the COMM START command without any parameters to list the services that have already been started.


Message 657

OS/2 error value occurred

EXPLANATION: An operating system error occurred while processing a COMM command. The OS/2 error code returned is shown. This message applies to OS/2-based clients only.

ACTION: Check the OS/2 error code shown.


Message 658

Another primary SNA Server already running.


Message 659

Invalid configuration file

EXPLANATION: The configuration file running when SNA Server was asked to start a service is invalid. It might be corrupted, or might not be a configuration file.

ACTION: Check to see that the COM.CFG file exists in the directory specified by the COMCFG share on the primary server.

If you need to replace the COM.CFG file, possible sources are the COM.CFG file on a backup server, or files with the extension .SNA, which is the default extension for backup configuration files created with the File menu Backup command. Copy the appropriate configuration file to the filename COM.CFG. Place the configuration file in the SYSTEM\CONFIG subdirectory of the SNA Server root directory.

If the error still occurs, call support services at your site.


Message 660

The SnaBase service could not find a primary or backup SNA Server.

EXPLANATION: The SnaBase service could not be started because there are no primary or backup servers running in the SNA Server network, and therefore there is no configuration file for the SNA Server components to read.

ACTION: Start a primary or backup server, and then restart the SnaBase service.


Message 661

There are no active network services

EXPLANATION: You used the COMM VIEW command without parameters, which provides a list of active services, but no services have been started. This message applies only to OS/2-based clients.


Message 662

There are no active network services at value

EXPLANATION: You used the COMM VIEW servername command to list all active services on the specified server, but no services were started on this server.


Message 663

The SnaBase service is already active on this computer

EXPLANATION: The SnaBase service could not be started because it has already been started on this computer. No action is necessary.


Message 664

Invalid SnaBase parameter value

EXPLANATION: The user attempted to start the SnaBase service with a parameter which is invalid.

ACTION: Start SNA Server services by using the Control Panel or SNA Server Manager. Specify the role of a server or client by using SNA Server Manager.


Message 665

The COMNAP service must be running to execute this command

EXPLANATION: The user on an OS/2-based client tried to run a COMM command without having started the necessary service.

ACTION: Start the COMNAP service and repeat the command.


Message 666

Services cannot be started on SNA Server client computers

EXPLANATION: Services cannot be started from an SNA Server client.

ACTION: Start the services from a server that contains the correct files to run the service.


Message 667

This computer is not configured to run the selected link service

EXPLANATION: To start a link service on a particular server, the correct device drivers must be configured in CONFIG.SYS.

ACTION: Use the Setup program to install the correct software and device drivers, and then start the link service. Refer to Microsoft SNA Server Getting Started for more information about installing the SNA Server product.


Message 668

Failed to open file value while checking that a backup configuration file was the same as the primary configuration file.

Retcode from CreateFile = value

EXPLANATION: A backup SnaBase was attempting to open its configuration file to check the file's date. The error means the backup file may not be the same as that on the primary server.

ACTION: If this error persists contact your support personnel.


Message 669

Failed to open file value while checking that a backup configuration file was the same as the primary configuration file.

Retcode from CreateFile = value

EXPLANATION: A backup SnaBase was attempting to get its configuration file age. The error means the backup file may not be the same as that on the primary server.

ACTION: If this error persists contact your support personnel.


Message 670

The primary configuration file value was successfully copied to value.

EXPLANATION: To maintain consistent configuration files across the subdomain, a backup SnaBase copied the configuration file from the primary server.

ACTION: None.


Message 671

Copy of file value to value failed.

Retcode on CopyFile was value

EXPLANATION: To maintain consistent configuration files across the subdomain, a backup SnaBase was in the process of updating a backup configuration file from the primary server.

It does this by:

1) Copying the backup COM.CFG to COM.BAK.

2) Copying the primary COM.CFG to COM.TMP.

3) Copying COM.TMP to the backup COM.CFG.

ACTION: The most common cause of this error is SNA Server Manager locking the file prior to writing a change. This will lead to retcode 32 and should clear once SNA Server Manager releases its lock. If the retcode is not 32 or this log is not eventually followed by the informational message 660 (indicating a successful copy), then contact your support personnel.


Message 672

Copy of file value to value has not been possible for over 5 minutes.

EXPLANATION: This message will have been preceded by a message 671. It indicates that the condition which initially prevented the file copy has persisted. Check message 671 for a retcode indicating the cause of the problem and follow the action suggested.

ACTION: See message 671.


Message 673

A Dload response specifying invalid Locality value was received.

EXPLANATION: This message may be received when SNA Server version 2.0 clients without patches are run in a 2.1 environment.

ACTION: Contact Microsoft Support for patches for your SNA Server version 2.0 clients or upgrade the client software.


Message 680

Failed to address remote buffer pool extension value

System return code value

EXPLANATION: An attempt was made to process a RamPipe to a local process and this failed. Possible causes include abnormal termination of the target process.

ACTION: If this message occurs repeatedly, or is accompanied by other severe errors then contact your support personnel.


Message 681

Failed to create remote buffer pool extension value

System return code value

EXPLANATION: An attempt was made to process a RamPipe to a local process and this failed. Possible causes include abnormal termination of the target process.

ACTION: If this message occurs repeatedly, or is accompanied by other severe errors then contact your support personnel.


Message 682

Remote buffer pool at maximum size

EXPLANATION: An attempt was made to process a RamPipe to a local process and this failed due to the target buffer pool having reached its maximum size.

ACTION: If this message occurs repeatedly, or is accompanied by other severe errors then contact your support personnel.


Message 683

Buffer inconsistency has been detected.

EXPLANATION: While processing a message, it was noticed that its structure was incorrect. This inconsistency would have led to corruption of the buffer pool, and then a trap at some point in the future.

To help locate the source of the corruption, the faulty component has been stopped and a dump initiated.

ACTION: Contact your support personnel.


Message 684

A buffer pool audit has been triggered by value

value

value

EXPLANATION: This audit contains information about the size of the buffer pool, how many headers and elements each process is using, etc.

ACTION: None, unless there is some other problem. In that case, report this log along with any others.


Message 685

An attempt was made to extend a buffer pool, but the related pool had reached its maximum size. The affected component is terminating, and an audit of the buffer pools just before termination is attached

value

value

EXPLANATION: This error is almost always due to either an SNA Server component (including possibly an emulator) losing buffers or a slow emulator (or RUI application) using a session without pacing.

ACTION: Contact your support personnel.


Message 686

SNA Server Internal buffer pool error.

Reason = value

Module = value

Process = value

Pool = value

Details = value

EXPLANATION: While processing a buffer pool request, it was noticed that the buffer pool had been corrupted.

To help locate the source of the corruption, the component has been stopped and a dump initiated.

ACTION: Provide your network support personnel with the information contained in this message.


Message 687

SNA Server is applying link back-pressure.

EXPLANATION: Possibly due to one or more slow applications using sessions which are not configured with pacing, SNA Server is now using almost all of its buffers to queue messages. To prevent the shortage becoming fatal, SNA Server is temporarily stopping the inflow of data from the links.

ACTION: Contact your support personnel.


Message 688

SNA Server has release link back-pressure.

EXPLANATION: Sufficient buffers are now available for continued processing of data from the links.

ACTION: None required.


Message 689

The RUI \ 3270 buffer pool has reached its maximum extension. This is a fatal condition and all of the pools users are now being terminated to maintain the stability of the server.

EXPLANATION: This error is almost always due to either an emulator losing buffers or a slow emulator (or RUI application) using a session without pacing.

ACTION: Contact your support personnel.


Message 690

SNA Server licensed session limit value exceeded. Number of active sessions is value.

EXPLANATION: Text to explain how the session limit is calculated and what action you should take.

ACTION: Contact your support personnel.


Message 691

Number of pending writes value exceeded the upper threshold value.

EXPLANATION: The number of pending writes has exceeded the configured upper threshold. The service which logged this event will stop sending new messages until the number of pending writes drops below the lower threshold.

ACTION: Contact your support personnel.


Message 692

Number of pending writes value has dropped below the lower threshold value.

EXPLANATION: The number of pending writes has dropped below the configured lower threshold. The service which logged this event will resume sending new messages.

ACTION: None required.


Message 693

Service Table Update to clients.

Reason = value

EXPLANATION: The service or application which logged this event generated a service table update to all clients.

ACTION: None required.


Message 694

SNA Server failed to add a PC-based service value. The VnsAddSvc() function failed with VINES error value.

EXPLANATION: SnaBase failed to create a Banyan VINES PC-based service. This step is necessary for the SNA Server to function correctly in a Banyan VINES network.

Most common error codes:

155 = The net/host is unreachable, communication problem between SNA Server machine and VINES Server.

1001 = Bad name, incorrect syntax appeared in a StreetTalk name.

1013 = No such object, StreetTalk cannot find this object.

1015 = Object already exists, an object with the same name already exists in the network.

1016 = Not an object name, the name specified is not a name StreetTalk knows.

1033 = Access denied, a user tried to change StreetTalk information without proper authorization.

1801 = User has not logged on to the VINES network.

ACTION: Contact your support personnel. The most common cause for this error is that the currently logged on user has not enough privileges to create a new VINES service, or there already exists another StreetTalk object with the same name.


Message 695

SNA Server failed to set the SPP port for service value. The VnsSetSSppPort() function failed with VINES error value.

EXPLANATION: SnaBase failed to set its own SPP port number. This step is necessary for the SNA Server to function correctly in a Banyan VINES network.

Most common error codes:

155 = The net/host is unreachable, communication problem between SNA Server machine and VINES Server.

1001 = Bad name, incorrect syntax appeared in a StreetTalk name.

1013 = No such object, StreetTalk cannot find this object.

1015 = Object already exists, an object with the same name already exists in the network.

1016 = Not an object name, the name specified is not a name StreetTalk knows.

1033 = Access denied, a user tried to change StreetTalk information without proper authorization.

1801 = User has not logged on to the VINES network.

ACTION: Contact your support personnel.


Message 696

SNA Server failed to add a StreetTalk list value. The VnsAddSStList() function failed with VINES error value.

EXPLANATION: SnaBase failed to create a StreetTalk list. This step is necessary for the SNA Server to function correctly in a Banyan VINES network.

Most common error codes:

155 = The net/host is unreachable, communication problem between SNA Server machine and VINES Server.

1001 = Bad name, incorrect syntax appeared in a StreetTalk name.

1013 = No such object, StreetTalk cannot find this object.

1015 = Object already exists, an object with the same name already exists in the network.

1016 = Not an object name, the name specified is not a name StreetTalk knows.

1033 = Access denied, a user tried to change StreetTalk information without proper authorization.

1801 = User has not logged on to the VINES network.

ACTION: Contact your support personnel. The most common cause for this error is that the currently logged on user has not enough privileges to create a new StreetTalk list or there already exists an other StreetTalk object with the same name.


Message 697

SNA Server failed to add the service value to the list value. The VnsAddSStMember() function failed with VINES error value.

EXPLANATION: SnaBase failed to add its name to the list of SNA Servers in the Windows NT domain. This step is necessary for the server to function correctly in a Banyan VINES network.

Most common error codes:

155 = The net/host is unreachable, communication problem between SNA Server machine and VINES Server.

1001 = Bad name, incorrect syntax appeared in a StreetTalk name.

1013 = No such object, StreetTalk cannot find this object.

1015 = Object already exists, an object with the same name already exists in the network.

1016 = Not an object name, the name specified is not a name StreetTalk knows.

1033 = Access denied, a user tried to change StreetTalk information without proper authorization.

1801 = User has not logged on to the VINES network.

ACTION: Contact your support personnel.


Message 698

Invalid Destination L-value. Parameter: value , Message: value , Valid range value - value

EXPLANATION: This was caused by an internal error in SNA Server. This error is usually followed by a more specific error message 699.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and internal trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 699

Invalid message: MsgType value , MhType value

Message Header: value

EXPLANATION: This was caused by an internal error in SNA Server.

ACTION: Provide network support personnel with the event log file(s) related to SNA Server, and internal trace file(s). For information about SNA Server log and trace files, see the Microsoft SNA Server Administration Guide.


Message 951

No application accepted received message.

EXPLANATION: A message was received by the SnaBase service which was not accepted by any currently running application. The application for which the message was intended may have been terminated unexpectedly.


Message 952

Failed to get application file name, rc = value


Message 953

The maximum number of applications for this client has been exceeded.

EXPLANATION: You attempted to start more than the maximum allowed number (40) of applications on a Windows-based client.


Message 954

DMOD request from unknown application (internal error).

EXPLANATION: An application made a call to a DMOD routine (such as sepdrout or sbpusend) without first registering with the DMOD using the sbpuinit call.

ACTION: For information about the sbpuinit call, see the 3270 Emulator Interface Specification.


Message 955

Could not get shared memory address from DMOD (internal error).


Message 956

SnaBase cannot be terminated while its services are being used.

EXPLANATION: You attempted to terminate the SnaBase service while applications (such as a 3270 emulator or APPC) are still running.

ACTION: Terminate all applications before terminating the SnaBase service.


Message 1000

The service called value is not configured in the registry as an SNA service


Message 1001

There is no configuration file COM.CFG in the directory value


Message 1002

This is a primary SNA Server yet the configuration file could not be found


Message 1003

SnaBase could not open a sponsor connection to server value


Message 1004

SnaBase didn't find any SNA Servers in your domain value


Message 1005

Unable to locate SNA Server Transport DLL.


Message 1006

Unable to access configuration information

ACTION: The SnaBase service was either unable to open the configuration file or unable to initialize SNACFG.DLL. The error code from SNACFG.DLL is value.

An error code of 0 means that the SnaBase service was unable to initialize SNACFG.DLL.


Message 1007

The SnaBase service could not Convert an ACL. Registry or File Security may not match what is specified in the SnaAdmin program. There error occurred at Code Check Point value due to NT Error Number value. The text of the NT Error is : value.


Message 1008

An unexpected exception occurred while converting an ACL. The Exception Code is value. The exception occurred near check point value.


Message 1009

The SnaBase service failed to build a security descriptor for registry and file use. The error occurred at Code Check Point value due to NT Error Number value. The text of the NT Error is : value.


Message 1010

An unexpected exception occurred while building a security descriptor. The Exception Code is value. The exception occurred near check point value.


Message 1011

The Security Descriptor for the config file has not been updated as SnaBase was not able to generate an appropriate Security Descriptor. (See previous Logs)


Message 1012

The Security Descriptor for the registry has not been updated as SnaBase was not able to generate a legal Security Descriptor. (See previous Logs)


Message 1013

The SnaBase service was not able to apply an updated Security Descriptor to the config file due to NT Error value. The text of the NT Error is value.


Message 1014

The SnaBase service was not able to apply an updated Security Descriptor to the registry due to NT Error value. The text of the NT Error is : value.


Message 1015

The SnaBase service was not able to get privileges required to maintain security. This may be because the account has not had the SE_SECURITY or SE_TAKE_OWNERSHIP privileges assigned to it. The NT error which occurred is value. The text of the error is value.


Message 1016

The SnaBase service was not able to open the registry key which contains domain security information. The NT Error which occurred is value. The text of the error is value.


Message 1017

Trying to validate the domain security descriptor, the SnaBase service determined that it is corrupted. The NT Error which occurred is value. The text of the error is value.


Message 1018

An error occurred attempting to impersonate a client. The client request was failed. The NT Error which occurred is value. The text of the error is value.


Message 1019

An error occurred trying to lookup a Privilege Value. The NT error which occurred is value. The text of the error is : value. The privilege being looked up was : value.


Message 1020

The SnaBase was unable to generate a valid SID for initial ownership of the SNA Domain. The Final Windows NT Error that occurred was value.

The text of the error is: value.


Message 1021

The SnaBase received a duplicate RU message number value from DLC.


Message 1950

RUI session abend for LU value


Message 1951

RUI buffer shortage, code = value


Message 1952

RUI_INIT complete for LU value


Message 1953

RUI link failure for LU value


Message 1954

RUI internal logic error for LU value, code value


Message 1955

RUI_INIT failed for LU value, primary_rc = value, secondary_rc = value


Message 1956

RUI_TERM complete for LU value


Message 1957

RUI application has ended: cleaning up session for LU value


Message 1958

RUI failed to extend session control block array, rc = value


Message 1959

RUI given bad event handle or callback address value


Message 3000

CPI-C semaphore operation error, system call return code: value


Message 3001

CPI-C failed to get configuration file path, (value)


Message 3002

Open of CPI-C configuration file failed, system call return code: value


Message 3003

CPI-C failed to get semaphore, system call return code: value


Message 3004

CPI-C failed to lock memory


Message 3005

CPI-C failed to allocate memory, system call return code: value


Message 3006

CPI-C failed to create call library semaphore, system call return code: value


Message 3007

New TP Instance started for CPI-C


Message 3008

CPI-C failed to get call library semaphore, system call return code: value


Message 3009

No CPI-C Conversation Characteristic Control Blocks available


Message 3010

Error while reading CPI-C configuration file, system call return code: value


Message 3012

CPI-C failed to access shared directory memory, system call return code: value


Message 3013

New CPI-C conversation accepted


Message 3014

New CPI-C conversation started


Message 3015

CPI-C conversation deallocated


Message 3016

CPI-C conversation in unknown state, value


Message 3017

CPI-C conversation_ID unknown, value value value value


Message 3018

Unknown CPI-C symbolic destination name specified, value


Message 3019

Invalid length of CPI-C data specified, value


Message 3020

Invalid CPI-C side information length specified, value


Message 3021

CPI-C attempt to Accept_Conversation after a conversation has been active


Message 3022

Attempt to exceed maximum number of concurrent CPI-C conversations: value


Message 3023

CPI-C failed to get memory pointer from handle


Message 3024

CPI-C failed to allocate memory


Message 3025

No CPI-C global control blocks available


Message 3026

CPI-C extract state call failed, APPC return code is value


Message 3027

CPI-C failed to get application name


Message 3028

Error returned from APPC that does not map to CPI-C error, value


Message 3029

No free CPI-C Side Information Directory entries


Message 3030

Invalid conversation_id parameter passed to CPI-C Accept_Conversation


Message 3031

Error from close of configuration file, return code is value


Message 3032

A Windows CPI-C application tried to start a conversation before issuing WinCPICStartup


Message 3050

Received value verb


Message 3051

Returning value verb, primary_rc value, secondary_rc value


Message 3052

No SNA Server management control blocks available


Message 3053

CSI return code value too large: mapping to default


Message 3054

Illegal CNOS FSM state


Message 3055

value received lost locality


Message 3056

Received CSI message for value control block value, which is not in use


Message 3057

CNOS received open (cs) error response, local LU alias value


Message 3059

Config semaphore error, rc = value


Message 3060

Error getting shared memory for DISPLAY, rc = value


Message 3061

Configuration file error, rc = value


Message 3062

Couldn't find a node record for the supplied connection, value


Message 3063

The local SNA Server has reached the configured limit for retrying connection value. It will no longer try to activate it.


Message 3064

Internal Error - an LUA session has returned an invalid status to RUI.

status_code=value

status_qual=value


Message 3065

A Bind sent by the host for a 3270 session was rejected

EXPLANATION: This was caused by an internal error in SNA Server.

ACTION: Report this error to SNA Server Support.


Chapter 10 Performance Monitor Counters

Performance Monitor counters are useful for evaluating the demand on and performance of the servers in your subdomain. You can obtain benchmarks and use the information to estimate hardware requirements for future growth.

The Performance Monitor is a graphical tool included in Windows NT. The Performance Monitor allows you to collect performance data on your computer or other computers on the network. To start Performance Monitor for SNA Server, make sure that all the services you want to monitor are active. Then, go to the Windows NT Administrative Tools and select Performance Monitor. The following screen appears:

Figure 10.1 The Windows NT Performance Monitor screen. The plus symbol on the tool bar will take you to the Add to Chart screen.

To view the performance counters listed below, click on the Plus (+) symbol. You can then add selected performance monitor counters to the chart using the dialog box. For detailed instructions, see SNA Server Manager online Help.

Figure 10.2 This screen allows you to choose which items to monitor.


Useful Windows NT Performance Counters

The following list describes objects and counters that may be useful for evaluating demand and performance on your Windows NT computer. For more information see your Windows NT documentation.

Memory: Pages/sec

In order to understand memory load on a Windows NT Server, it is necessary to understand paging, a technique for implementing virtual memory. Paging is the swapping of blocks (pages) of program instructions or data back and forth between memory and disk, and is carried out as needed by the virtual memory manager in Windows NT.

Pages/sec is the number of pages read from the disk or written to the disk because they were not in memory when needed (that is, the number of "page faults" that required disk access.) The counter includes paging traffic generated when the cache accesses file data for applications.

This is the primary counter for determining whether your server is paging excessively (or "thrashing".) As this counter goes up, server responsiveness slows because of the time required for disk access (reading or writing). A server dedicated to communications should be equipped with enough physical memory so that little paging is required.

The highest acceptable value for Pages/sec varies from system to system. One way to judge whether system load is causing too much paging is to observe whether processor activity (System: %Total Processor Time) drops significantly as paging increases. This indicates that the system is occupied with swapping pages rather than with actually processing instructions.

The primary ways to correct excessive paging is to add more physical memory to the server or to consider ways to decrease the demand on the server. Demand can be decreased by narrowing the variety of tasks that a server must perform or by decreasing the number of users accessing a server. For example, an overloaded multipurpose server (with file, print, and SNA Server demands) could be dedicated to SNA Server traffic only. Or, as another example, user loads placed on one server could be divided between two servers (load balancing). As mentioned, in any case of memory overload, adding physical memory may provide the needed performance increase.

A secondary way to decrease the impact of paging is to upgrade the disk system to be more efficient. This includes installing a faster disk, installing a second disk, using RAID striping, or similar upgrades. This upgrading does not decrease paging (Pages/sec), but speeds up the paging process itself. For example, replacing a slow IDE disk with a faster SCSI disk may make a given paging rate (perhaps 20 – 40 pages/sec) acceptable.

System: %Total Processor Time

Processor: %Processor Time

System: %Total Processor Time is the percentage of elapsed time during which the system processors are busy. It can be viewed as the fraction of total processor time spent doing useful work. Values of 60 – 80 percent during typical loads are good values, because they allow some reserve for peak loads. However, when the processor stays at 100 percent for periods of time, this may indicate a processor bottleneck. On a multiprocessor system, you can view Processor: %Processor Time for each processor, to see how the load is distributed among processors.

One useful way to view Total Processor Time values is in Chart view along with counters indicating increases and decreases in user load. For user load, such counters include logical unit sessions: Throughput Bytes/Sec, and SNA Adapter adaptername: Throughput Frames/Sec. These two counters are available only when there is SNA activity. For example, you might notice that during a period of peak demand for logical unit sessions, Total Processor Time reaches 100 percent and stays there. This could indicate that the SNA Server is reaching peak capacity and that any future additional demand might require additional processors or additional servers.

It may also be helpful to view System: %Total Processor Time along with any other counters related to the server's major functions. For example, for an SNA Server that is also a file server, the Server: Server Sessions counter may be helpful. Other counters that may help you analyze the sources of processor activity are Process: %Processor Time for processes you think are relevant, as well as System: Total Interrupts/sec. Also, if your clients are using NetWare, consider looking at NWLink SPX: Connections Open. Similarly, if your clients use TCP/IP, consider looking at TCP: Connections Established.

System: Total Interrupts/sec

Processor: Interrupts/sec

System: Total Interrupts/sec is the rate at which the computer is receiving and servicing device interrupts. (Device interrupts are the signals a device sends to a processor to indicate that a task is complete or that the device requires attention.) Some devices that may generate interrupts are adapters, network adapters, the system timer (clock), and the mouse. System: Total Interrupts/sec provides an indication of how busy these devices are on a computer-wide basis.

Similarly, for each processor, Processor: Interrupts/sec is the rate at which the processor is receiving device interrupts.

Normal thread execution is suspended during interrupts. An interrupt may cause the processor to switch to another, higher-priority thread. Clock interrupts are periodic and frequent (on the order of 100/sec); they create a background of interrupt activity.

These counters can help indicate the general demand on a server, and may be useful when combined with processor and memory data such as System: %Total Processor Time and Memory: Pages/sec.


SNA Server Performance Counters

The following list describes objects and counters in SNA Server that may be useful for evaluating demand and performance on an SNA Server computer.

The counters are chosen via the Object pull-down box. The objects that are specific to SNA Server are:

  • SNA Adapter <adapter name>
  • SNA Connections
  • SNA Logical Unit Sessions
  • TN3270 Server

Many of the objects have common counters, such as Data Bytes Received/Sec and Data Bytes Transmitted/Sec. Each counter is discussed below only once with a reference given to each object that has the counter.

Adapter Failures

The number of times since startup that a network adapter encountered an error condition.

Object location:

SNA Adapter adaptername

Connection Failures

The number of times since startup that a connection has failed.

Object location:

SNA Adapter adaptername

Databytes Received/Sec

This is the number of data bytes received per second.

Object location:

SNA Adapter adaptername

SNA Connections

SNA Logical Unit Sessions

Databytes Transmitted/Sec

This is the number of data bytes transmitted per second.

Object location:

SNA Adapter adaptername

SNA Connections

SNA Logical Unit Sessions

Frames Received/Sec

The number of data frames received per second. A frame is an information structure organized by one of the various protocols related to SNA.. Frames contain multiple bytes of data.

Object location:

SNA Adapter adaptername

Frames Transmitted/Sec

The number of data frames transmitted per second.

Object location:

SNA Adapter adaptername

Successful Connects

The number of times since startup that a successful connection has been made.

Object location:

SNA Adapter adaptername

Throughput Bytes/Sec

The total number of bytes flowing through SNA Server per second. This includes both incoming and outgoing bytes, and is a good indicator of how heavily your SNA Server computers are loaded.

Object location:

SNA Adapter adaptername

SNA Connections

SNA Logical Unit Sessions

Throughput Frames/Sec

The total number of data frames flowing through SNA Server per second. This includes both incoming and outgoing frames, and is a good indicator of how heavily your SNA Server computers are loaded.

Object location:

SNA Adapter adaptername


Additional Information

SNA Connections: Throughput Bytes/Sec

SNA Logical Unit Sessions: Throughput Bytes/Sec

SNA Adapter adaptername: Throughput Frames/Sec

These counters provide an indication of SNA activity. When observing these counters, it may also be useful to start SNA Server Manager and double-click on the server (the same one being observed in Performance Monitor). This will allow you to see the number of users and sessions that correlate with a particular level of SNA activity. This information, combined with data about the processor and memory load, can help you understand the load and performance on your servers. Low throughput does not necessarily mean poor performance, but instead may simply indicate that current activity is low.

Measurement of frames/second may provide a better indicator of server load than bytes per second, because server overhead (for interrupt handling and message processing) increases per frame, not per byte. That is, a large frame with many bytes requires about the same overhead as a small frame with fewer bytes.

For suggested ways to tune SNA Server to maximize communications throughput, see "Options for Maximizing Communications Throughput."

SNA Connections: Data Bytes Received/Sec

SNA Connections: Data Bytes Transmitted/Sec

SNA Logical Unit Sessions: Data Bytes Received/Sec

SNA Logical Unit Sessions: Data Bytes Transmitted/Sec

SNA Adapter adaptername: Data Bytes Received/Sec

SNA Adapter adaptername: Data Bytes Transmitted/Sec

SNA Adapter adaptername: Frames Received/Sec

SNA Adapter adaptername: Frames Transmitted/Sec

SNA Adapter adaptername: Throughput Bytes/Sec

These counters provide additional detail about SNA activity when used with the previous three counters.

SNA Adapter adaptername: Adapter Failures

SNA Adapter adaptername: Connection Failures

SNA Adapter adaptername: Successful Connects

These counters may be useful for detecting patterns in which connections or adapters fail for short periods and then return to normal. (Event logs can provide more information about causes of failure.) You might also want to set up Performance Monitor alerts with these counters, so that an alert is triggered if too many failures are occurring.


TN3270 Performance Monitor Counters

This section describes the Performance Monitor counters for TN3270 service. The object is TN3270 Server. The following are the counters for the TN3270 Server object:

Connections Active

The number of TCP connections currently active.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

RU Throughput

This is the total number of RUs sent and received by TN3270 service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

RU Throughput/sec

The rate at which RUs are being sent and received by TN3270 service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

RUs Inbound

The total number of RUs sent to the IBM host by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

RUs Inbound/sec

The rate at which RUs are being sent to the IBM host by TN3270 Service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

RUs Outbound

The total number of RUs received from the IBM host by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

RUs Outbound/sec

The rate at which RUs are being received from the IBM host by TN3270 Service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

Sessions Active

The number of TN3270 clients currently using an LU.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Configured

The number of sessions available to TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Ended LULU

The number of TN3270 client sessions that were terminated while in session with an IBM host application.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Ended Normal

The number of TN3270 client sessions that were terminated normally.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Failed

The number of TCP/IP connections that were actively terminated by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Failed Inactivity

The number of TCP connections that were actively terminated by TN3270 Service due to inactivity.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Failed No Resource

The number of TN3270 client sessions that were rejected because no SNA Resource could be obtained.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

Sessions Succeeded

The number of TN3270 client sessions that have successfully obtained an LU since TN3270 Service was started.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

TCP Bytes Received

The total number of TCP bytes received by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

TCP Bytes Received/sec

The rate at which TCP bytes are being received by TN3270 Service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

TCP Bytes Sent

The total number of TCP bytes sent by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

TCP Bytes Sent/sec

The rate at which TCP bytes are being sent by TN3270 Service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

TCP Throughput

The total number of TCP bytes received and sent by TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes

TCP Throughput/sec

The rate at which TCP bytes are being received and sent by TN3270 Service.

Counter Type: PERF_COUNTER_COUNTER

Default Scale: 1 Counter Size: 4 bytes

Users Active

The number of different TCP/IP addresses currently active in the TN3270 Service.

Counter Type: PERF_COUNTER_RAW_COUNT

Default Scale: 1 Counter Size: 4 bytes


MS SNA Server Tools

<CD picture here> To install the SNA Server Resource Kit utilities, insert the compact disc labeled BackOffice Resource Kit II Utilities and run setup.exe from the root directory. For more information on installing the SNA Server tools, please see the Microsoft SNA Server Tools Documentation in the Helpfile (snatools.hlp).

The Microsoft SNA Server Tools Help file explains how to use the Microsoft SNA Server utilities provided in the Microsoft BackOffice Resource Kit. Setup and usage tools are provided for each utility.

Before installing any of the utilities for SNA Server, consult the Release Notes for any important installation and configuration information. It is recommended that you install the utilities using the Microsoft BackOffice Resource Kit CD-ROM. After installation, you can then move or copy the utilities to the appropriate directories.

All of the SNA Server utilities are installed in the c:\BORK\SNA directory. Each utility will run from this directory.

All but one of the utilities provided on the CD-ROM will only run on computers with Intel processors. The exception is the CLEANUP.EXE tool, which can run on computers with Intel, MIPS, Alpha, and PowerPC computers. For more information about CLEANUP.EXE see the documentation provided in the Microsoft SNA Server Tools Helpfile.

Before using any of the utilities on the CD-ROM, please read the Disclaimer.

The following tools are available for administering or enhancing SNA Server:

CLEANUP.EXE removes all SNA Server services, Registry entries, and files.

ACTIVELU lets you implement a COM wrapper to an SNA LUA API and expose an automation interface.

DISPLAY.EXE shows the number of active SNA Server computers in your subdomain, in addition to other important SNA Server information.

BITFLIP.EXE allows you to bit-flip Ethernet mac addresses for entry on the 3174 940 panel and to bit-flip token ring addresses.

BINDERY.EXE allows you to obtain a list of SNA Server computers, their subdomain names, and their IPX addresses registered in the NetWare bindery.

DRWATSON.EXE allows you to perform diagnostics on 16-bit applications and systems.

HEAPWALK.EXE displays 16-bit Windows processes running on a Windows 3.x, Windows 95, or Windows NT system.

SNATALK.EXE will list SNA Servers and their Banyan VINES StreetTalk addresses.

Note Banyan VINES requires the VNSAPI32.DLL. This DLL is not included with SNA Server or the Windows NT operating system. It is included in the Banyan VINES Enterprise Client for Windows NT software.

GETSENSE.EXE displays four- or eight-digit APPC messages.

APPCTest is a Visual Basic application to help developers create APPC APIs. This program tests APPC API verbs and should be used in conjunction with the Microsoft SNA Server APPC Programmer's Guide.


Disclaimer

Many of these tools were developed internally at Microsoft. Any use of any of these tools is at your own risk. These tools are provided "AS IS" without warranty of any kind. Microsoft disclaims any implied warranty of merchantability and/or fitness for a particular purpose.

These tools have NOT been localized: they are written and tested in English only. Using these tools with a different language version of Microsoft SNA Server may produce unpredictable results.

Many of these tools are designed to work only if you are logged on as a member of an Administrators group.


Correction to SNATools.hlp

The online help file for SNATALK states that "Banyan VINES requires the VNSAPI32.DLL." The DLL is delivered with the Banyan VINES Enterprise Client. It is SNATALK.EXE that requires this DLL to run properly.


Setup Instructions for APPCTest

APPCTest is not installed during installation of the BackOffice Resource Kit. The following instructions will install a working copy of APPCTest:

Install the BackOffice Resource Kit from the CD-ROM.

Locate the APPCTest folder in the SNA folder on the hard drive.

Click Setup up to install APPCTest.

Follow the dialog box prompts to complete installation.


Microsoft SNA Server File List

In the Bork\SNA directory:

BINDERY.EXE | Bindery application file
BITFLIP.EXE | BitFlip application file
CLEANUP.EXE | SNA Server removal application (command-line tool)
CLEANUP.INI | Required for running Cleanup.exe
DISPLAY.EXE | SNA Server Display application (command-line tool)
DRWATSON.EXE | 16-bit event log application
GETSENSE.EXE | APPC error code display application (command-line tool)
HEAPWALK.EXE | Application to display 16-bit Windows information
SENSDATA.DAT | The GETSENSE data file
SNATALK.EXE | Tool to list SNA Server computers and their Banyan VINES StreetTalk addresses.
TOOLS.CNT | Microsoft SNA Server Help Contents
TOOLS.HLP | Microsoft SNA Server Help
WINDEF.HLP | Microsoft Help window definition

In the Bork\SNA\ActiveLU directory

ACTIVELU.DLL | DLL required for ActiveLU.exe
ActiveLuClient.exe | ActiveLU client application
CRREMOBJ.DLL | Required DLL for ActiveLU.exe
RemoteLUPool.exe | Application to determines remote LUs
RLPCLNT.EXE |
RLPEXPL.EXE | Remote LU Pool Explorer displays the status of LUs in pools


Introduction

Welcome to the Microsoft® Systems Management Server Resource Guide, Supplement One. This guide is designed for people who are, or who want to become, expert users of Microsoft Systems Management Server (SMS). The Microsoft Systems Management Server Resource Guide, and this Supplement, are technical supplements to the documentation included as part of the SMS product and do not replace that information as the source for learning how to use SMS.


About the Resource Guide

This guide includes the following chapters.

Chapter 1, "Deploying Software with SMS," Describes how to use SMS to deploy Windows NT 4.0 and Office 97 throughout your organization.

Chapter 2, "Working with Systems Management Server," Describes a variety of tips for working with SMS. Includes information on unattended installation of SMS clients, interpreting SNMP traps, and SMS registry entries. Also includes information on the new PCM service for SMS 1.2 clients.

Chapter 3, "Troubleshooting Remote Control," Provides many useful tips for working with SMS Remote Control.

Chapter 4, "Tools," Describes tools included with this BackOffice Resource Kit.


Conventions in the Resource Guide

The following tables summarize the typographic conventions used in this book.

Convention | Meaning
bold | Characters that you type exactly as shown, including commands and switches.
Italic | Variables for which you supply a specific value. For example, SYSTEMROOT in a path name could refer to C:\WINNT35 or to some other path where Windows NT is installed on a specific computer.
ALL CAPITALS | Names of paths, directories, files, and acronyms. Unless otherwise indicated, you can use uppercase or lowercase when you type paths, directories, or file names.
Monospace type | Examples of code.
[ ] (square brackets) | In syntax descriptions, square brackets enclose optional items. If you include the item, type only the information between them, not the square brackets themselves.
{choice1 | choice2} (braces) | In syntax descriptions, braces enclose items which require a choice, such as {yes | no}. Type only one of the choices, not the braces or the dividing line.
Menu | Command (menus) | In referring to menu choices, Edit | Paste, for example, means to select the Edit menu and then choose the Paste command from it.

Keyboard Conventions

Convention | Meaning
SMALL CAPITALS | Names of keys that you press, such as TAB.
+ (a plus sign between two or more key names) | Indicates that you must press the keys at the same time; for example, ALT + TAB.
, (a comma between two or more key names) | Indicates that you must press each key consecutively; for example, ALT, F, X.

Terminology Conventions

Convention | Meaning
"Command prompt" | refers to the point on the MS-DOS screen where you enter commands, typically designated by "C:\>" (or other characters indicating the current drive and directory). To reach the command prompt in Windows NT, double-click the MS-DOS Prompt icon in Program Manager.
"Command-line application" or "console-based application" | refers to an application designed to run under MS-DOS or in an MS-DOS window, and which cannot run in a Windows or Windows NT window.
"Windows-based application" or "GUI application" | refers to an application that must run in a Windows® or Windows NT window. All such applications follow similar conventions for the arrangement of menus, dialog box styles, and keyboard and mouse use.

Procedural Conventions

  • Procedures describing how to do a task are preceded by a triangular bullet ( Û) for a single step or numbers for multiple steps.
  • An instruction to "type" information means to press the key or keys and then press the ENTER key.
  • An instruction to "select" information means to highlight directories, file names, text boxes, menu bars, and options, or to select options in a dialog box.
  • An instruction to "choose" something means to carry out a command from a menu or dialog box with mouse or keyboard actions.
  • "Note" alerts you to supplementary information.
  • "Caution" alerts you to possible data loss or breaches of security.


Where to Look for More Information

You can find additional information about SMS version 1.2 in the product documentation, in the Systems Management Server Resource Guide included in the first BackOffice Resource Kit, and on the SMS Web sites described in the following sections.


Chapter 1 - Deploying Software with Systems Management Server

With SMS, you can deploy operating systems and applications to client computers throughout your network from a central location. This chapter discusses issues involved in deploying Windows NT 4.0 and Office 97.

If you are planning to deploy either Windows NT or Office throughout your organization, you need to be thoroughly familiar with the features of and the setup program for the software. In addition to the product and product documentation, you should have available the resource kit for the product. The resource kits provide detailed information on deploying the product, as well as tools that you can use to manage the software in your organization.

PDF files are included on the Windows NT and Office 97 product CD-ROMs, and on the Microsoft Office 97 Resource Kit CD-ROM. You can use these PDF files as-is, modify them, or create new PDF files to distribute the software. The easiest way to create a new PDF file is to use SMS Admin to create a package, and then use WRITEPDF.EXE (from this Resource Kit) to export the package to a PDF file. If the job will need to reboot the client computer, you must then edit the PDF file, changing the value of synchronousExitRequired from False to True.

If you need to create a PDF and do not have access to a computer running SMS Admin, you can use PDFWIZ.EXE (also included in this Resource Kit) to create the package. However, the package will need to be reviewed and edited in SMS Admin before it is used.


Deploying Windows NT 4.0 with SMS

The setup program for Windows NT 4.0 allows a completely scripted installation. In addition, the installation can be completely customized. You can even specify per-computer settings in your scripted installation. The Windows NT Workstation Resource Guide provides information on customizing your installation. The Windows NT Server Resource Kit includes the Windows NT Workstation Resource Guide as an online book.

Before you use SMS to deploy the Windows NT Workstation or Windows NT Server operating system to SMS clients, you'll need to complete the following tasks:

  • Select the sites containing client computers that you want to upgrade.
  • Create a source directory for the Windows NT Workstation and/or Windows NT Server files.
  • Import the PDF to distribute the operating system. A prepared PDF is available on the Windows NT CD-ROM.
  • Edit the Windows NT answer files as needed for your organization.
  • Use queries to identify which clients have the memory, disk space, and microprocessor required to run the new operating system. Also, query for legacy applications that may not run with the new operating system because they require access to shared memory.
  • Use the query results to create a machine group that contains all the computers you will upgrade to the new operating system.
  • Create a job to distribute the operating system.
  • Monitor the SMS job status.
  • Evaluate distribution results.


Preparing the Source Directory

Use the following procedure to create and populate a package source directory for your Windows NT Workstation and/or Windows NT Server source files. This directory will also contain the answer files (UNATTEND.TXT) and uniqueness database files (UDFs) that allow you to deploy Windows NT without user intervention at the target computers.

To create a package source directory

Create a source directory for the Windows NT operating system files. Within this source directory, create subdirectories for each processor type (i386, Alpha, or MIPS).

Share the directory using a share name that is identical to the directory name.

From a client computer or from the server containing the package source directory, log on to the network and connect to the share you created.

Insert the Windows NT CD-ROM and use the xcopy command to install the operating system files in the package source directory. Copy all the files for every platform supported in your organization, preserving the directory structure on the CD-ROM or installation disks. For example, if your organization uses x86-based computers but not Alpha or MIPS computers, you would need to copy the \i386 directory tree (but not the \Alpha and \MIPS directory trees) to your package source directory.

Copy the UNATTEND.TXT file from the Windows NT 4.0 CD-ROM to the source directory.

  • If you will be targeting Windows NT systems for upgrade, copy UNATTEND.TXT to NTUPGRD.400.
  • If you will be targeting MS-DOS or Windows 3.1, Windows for Workgroups, or Windows 95 clients for upgrade, copy UNATTEND.TXT to UNATTEND.400.

Modify the UNATTEND.400 and NTUPGRD.400 files for installation as required by your configuration. See the Windows NT Workstation Resource Guide for details. (This book is included online in the Windows NT Server Resource Kit).

In the UNATTEND.400 file, leave the ComputerName entry (in the [UserData] section) blank if you want SMS to fill in this value using the one specified in the SMS.INI file, or if you will be using a Uniqueness Database File (UDF) to tailor the installation to individual computers. For information on creating answer files and UDF files see Part I, "Deployment Guide," in the Windows NT Workstation Resource Guide.

Copy your UDF and any other files used in a customized setup to the package source directory. If you will be installing applications along with Windows NT, the files for those applications also need to be copied to the source directory. Chapter 2, "Customizing Setup," in the Windows NT Workstation Resource Guide explains the directory structure to use for these files.


Creating the Windows NT Package in the SMS Administrator

The following procedure tells you how to create a package to install Windows NT using the PDF included on the Windows NT Workstation or Windows NT Server CD-ROM. This procedure assumes that you have already created the source directory for the Windows NT files.

To create the package

In SMS Administrator, open the Packages window. On the File menu, click New.

The Package Properties dialog box appears.

Click Import.

The File Browser dialog box appears.

Click the file NT40.PDF from the i386 or Alpha directory on the Windows NT CD-ROM, and then click OK. If you have copied the source files to a server, you can import the NT40.PDF file from the i386 or Alpha directory on the package server share.

Click Workstations.

The Setup Package for Workstations dialog box appears.

In the Source directory box, type the location of the package source directory and then click Close.

If the package source directory will be accessed by other computers, and you choose to browse through the list of files, edit the resulting path so that it shows the UNC name (which would begin with \\servername\sharename) rather than the relative name (which would begin with the drive letter you have assigned to the server during the current session).

Click OK to close all open dialog boxes.

The "Windows NT Capable" Query

The goal of a "Windows NT Capable" query is to help identify the computers that have the hardware required to run Windows NT. After you create and run the query, you can create a machine group with the results. This will be your target group for the jobs to install Windows NT. Later, you can run another query on this group to make sure the new operating system is running on the targeted computers.

Note You may find it helpful to give each machine group the same descriptive name as the query you used to create the machine group.

Depending on your organization, you might want to use modified versions of a basic query.

The query should check for the following:

  • Current operating system
  • Processor type (Intel or Alpha)
  • Available hard disk space
  • Installed RAM

To successfully upgrade a computer to Windows NT, the computer must have available at least 92 MB more disk space than Windows NT requires. At least 5 MB of this space must be on drive C of the computer; the rest can be on any local hard drive. This extra disk space is used to store files during the upgrade.

Because the PDF has multiple command lines (for installing Windows NT to computers currently running MS-DOS, Windows, Windows 95, or Windows NT), you will need multiple queries to define the target workstations for the different platforms. This information will be used in defining the job details when you send the job to install Windows NT.

To find all the Windows for Workgroups computers that can run Windows NT Workstation, use a query similar to the following:

(

MICROSOFT|DISK|1.0:Free Storage (MByte) is greater than or equal to '40'

AND

MICROSOFT|DISK|1.0:Disk Index is 'C'

)

AND

MICROSOFT|X86_PC_MEMORY|1.0:Total Physical Memory (KByte) is

Þ greater than or equal to '16000'

AND

(

MICROSOFT|PROCESSOR|1.0:Processor Name is like '486'

OR

MICROSOFT|PROCESSOR|1.0:Processor Name is like 'PENTIUM'

)

AND

MICROSOFT|OPERATING_SYSTEM|1.0:Operating System Name is

Þ 'MS Windows for Workgroups'

This query is available in the folder SMS\Queries on the BackOffice Resource Kit CD-ROM.

SMS records the MS-DOS versions of all computers running MS-DOS, Windows, Windows for Workgroups, or Windows 95. This means that all workstations that meet the criteria of the query will be targeted for the installation, including existing Windows NT computers.

Note In the inventory, the MS-DOS version for Windows 95 is recorded as version 7.0. SMS does not report a MS-DOS version for Windows NT Workstation or Windows NT Server platforms.

You can modify the properties of the "Windows NT Capable" query and save it with a unique name. For example, if you have both 486 and Pentium computers that are "Windows NT Capable" but only want to target the Pentium computers, you would edit the query to specify this restriction. Save each of the specialized queries you create.


Create a Job to Run the Package on Clients

Before you can create a job to deploy Windows NT, you need to select the target computers for the job. In some cases, the target computers will be all of the computers in a site. Often, though, you'll want to deploy the new operating system to a specific subset of the computers. The queries you imported or created, as described in the previous section, can be used to define a group of computers.

You can create a job by dragging the package to a query. Or, you can run the query and create a machine group (an alias for a group of computers) from the query results, then send the job to that machine group. If you use a machine group, you can query the computers in that group after the deployment job has completed to make sure that the installations were successful. If you send the job to the query results directly (by dragging the package to a query) you don't have this option, since the computers that met the query criteria before deployment are not likely to meet those criteria after deployment.

To create a machine group of your target computers, run your "Windows NT Capable" query, then drag and drop the query results into a machine group in the Machine Group window. You can also use multiple variations of the query to create different machine groups that will receive different configurations. All the queries should be tested before proceeding further, to ensure that you are selecting the computers you want to target.

To distribute the package

In SMS Administrator, open the Packages window and then open the Sites window.

In the Packages window, select the package you created for the operating system, and drag it onto the machine group (in the Machine Groups window) created from the results of your "Windows NT Capable" query. This creates a Run Command on Workstation job.

Complete the Job Details dialog box by choosing the xcopy command.

You will probably want to set the value in the Expires After list box to something less than the default of six months. Once a job is distributed, the associated instructions are kept in the instruction file on each affected logon server until the job expires or is canceled, even after the job has completed on all target computers. This consumes about 3K per job per logon server. Specify an expiration date that is realistic for your organization and for the job.

You might also choose to take advantage of the job scheduling and configuration options. If so, remember to set the priority to Low.

For more information about the Job Details dialog box, see the Systems Management Server Administrator's Guide.

Click OK to close open dialog boxes.

Note Before upgrading an operating system, users should close all open applications and disconnect all shared resources on their computers. If an application has unsaved data, or if a shared connection is in use, the operating system Setup might not be completed successfully.


Validate the Windows NT Deployment

After deployment, evaluate the distribution results on the upgraded clients. Note that a Complete job status does not necessarily indicate successful deployment of Windows NT. You must perform additional analysis to determine the results of deployment:

  • Make sure that the SMS client inventory has been updated for all clients in the target group.
  • Use queries to determine whether the upgrade succeeded.
  • Test the clients that were successfully upgraded to ensure that the configuration you specified works as expected on these computers.

Some computers in your target group may not have been successfully upgraded. You can deal with these on a case-by-case basis. Here are a few of the things you can check in these cases:

  • If you marked the Inventory This Package check box in the Setup Package for Inventory dialog box when you created the package, you can examine a copy of the Setup log file created on each target computer. Study this file to determine the cause of any problems. For example, there might have been changes in available disk space or in the availability of some other resource between the time the computer was added to the target group and the time the upgrade was performed.
  • Check the details of job events to troubleshoot problems. For example, if a job has failed because the answer file (for example, UNATTEND.400) was not available where it was expected, this would be reported in the job events.
  • Determine whether any individual clients, which may have failed during the Windows NT upgrade process, are no longer operational.

    Clients that are no longer operational are not updated in the SMS inventory. You might choose to perform the inventory at more frequent intervals before deployment to make sure that only currently operational computers are targeted. In some cases, you might want to develop an SMS query to identify clients that have not had their inventory updated.

  • Determine whether a faulty hardware component caused a failure of the Windows NT upgrade process.


Special Considerations for Any Operating System Upgrade

When you use SMS to deliver a new operating system, there are special considerations that do not apply when you are delivering an application. Most of these considerations stem from the fact that the computer needs to be restarted as part of the installation process.

Computer Is Restarted After Upgrading

When an operating system Setup job is run, the computer is restarted at the end of the upgrade process. The user must log back on to the network after the computer is restarted.

Client computers will be restarted during the upgrade process. In some cases, an application might be running on the client computer when the job to upgrade the operating system starts. If the application has unsaved, altered data files open when it is time for the upgrade program to restart the system, the program will require input from the user before it restarts the system. If a user is not present to provide this input, the job is delayed until the user is present to provide the input.

Once a computer has been upgraded to a new operating system, the SMS software components residing on it locally must be upgraded. For upgrades from MS-DOS, Windows 95, or any 16-bit Windows operating system, the user's SMS client components will be upgraded the next time the user logs on to the new operating system if the user has a logon script that runs the SMSLS.BAT file. Users who do not have such a logon script must connect to the SMS logon server and run the RUNSMS.BAT file manually. If you are upgrading from an earlier version of Windows NT, the SMS component is upgraded automatically by SMSRUN.

Note Because operating system upgrade jobs require the computer to be restarted when the upgrade is completed, any other mandatory SMS jobs scheduled on the client computer immediately after the operating system upgrade will not occur at the scheduled time. Therefore, be sure to leave adequate time between scheduling a mandatory operating system upgrade job and any other mandatory SMS jobs (such as application installations) on the same client computer.

Reported Status of Operating System Upgrades

At some point during each operating system upgrade job, control of the upgrade process is handed off from SMS to the Setup program of the operating system being upgraded. If the operating system Setup program fails after this point for any reason, the failure will not be reported back to SMS, and SMS will report the job client status as completed.

When you create and send operating system upgrade jobs, you should plan and test the process on a small sample of client computers before attempting to distribute the job to a large number of client computers. This will give you the opportunity to identify errors in scripting components that are specific to the operating system, while the impact is minimal.

Windows NT Computers

When upgrading a computer running Windows NT, the computer must retain the same role. For example, if the computer uses Windows NT Workstation, it cannot be upgraded to Windows NT Server. You must do a clean installation to change the role of a computer.

Computers With Multiple Operating Systems

Before upgrading an operating system for a client computer with more than one operating system:

  • The computer must be identified in the SMS inventory by the operating system that you want to upgrade, and it must currently be running that operating system.
  • The upgrade job must be sent to that computer and specified as valid for the current operating system (so that it shows up in Package Command Manager at the client computer.)
  • The computer must be configured to restart to the current operating system so that the upgrade script can be completed.


Deploying Microsoft Office 97 with SMS

You can use SMS 1.2, with Service Pack 1, to deploy Office 97 to clients on your network. A standard PDF file is included with Office 97 to help you install Office locally on client computers using a Typical, Custom, or Complete installation. The Microsoft Office 97 Resource Kit includes a PDF that supports remote Run from Network Server installations, as well as installation modes supported in the standard PDF. While this document assumes you have access to the PDF included in the Microsoft Office 97 Resource Kit, most of the instructions also apply when you are using the PDF on the product CD-ROM.

Before you deploy Office to SMS clients:

  • Review the Office feature set and decide which components to install on the clients.

    You can take advantage of user profiles to require that a mandatory desktop configuration be loaded each time a user logs on. (For more information, see your Microsoft Office 97 documentation.)

  • Decide on configuration and installation options, such as file locations, installation media, and installation method. (For more information, see the Microsoft Office 97 Resource Kit.)
  • Decide which existing files, macros, and custom programs you will need to use in the new software, and identify any extra steps that might be required to use the existing files and macros in Office.
  • Use SMS queries to identify which clients have the hardware required to run Office.
  • Run a test to identify any issues in deploying Office on your network.

The Microsoft Office 97 Resource Kit, from Microsoft Press, is a technical supplement to the Office product documentation. It was written to assist administrators in installing, supporting, and managing Office on corporate networks.


Defining the Preferred Client Configuration

Before specifying the preferred configuration for clients, you should:

  • Understand the current server and client configurations.
  • Select the features that will be used in the preferred configuration on clients.
  • Select the features that will be used to enable users to work together.
  • Decide where Office files will be located and how they will be installed. That is, will Office files be installed on the client's hard disk, or will they be installed on a server and accessed remotely by the client, or a will a combination of both be used?

Researching Current Configuration Variables

To deploy Office successfully, you need to understand your current hardware and software configurations. Your deployment plan will be dictated by your current system environments.

  • Hardware configuration
    • For minimum hardware requirements, and to determine whether any clients need to be upgraded, see the Microsoft Office 97 Resource Kit.
    • Laptop and desktop users have different configurations, including disk space and access to the network. Installation options will need to be selected with the specific client in mind.
  • Network topology
    • You can install software on clients from a network server, or you can run Office applications as SMS network applications. You may need to configure differently in each of these cases.
    • Installing or running Office remotely over the network may not be practical for clients connected over a slow-link network. You may need to install Office 97 on these clients from the CD-ROM.
    • Use of different network operating systems can create issues such as server file-sharing methods and client-server permission schemes.
    • Installing Office over the network and running Office applications over the network place different demands on network bandwidth, both in response time and in length of time connected.
    • Users without network access must install Office locally, from the Office 97 CD-ROM.
  • Migrating existing configurations

    Determine whether you need to convert existing files, macros, and custom programs, and how you will train new users of Office 97. For more information, see the Microsoft Office 97 Resource Kit.

  • Supporting multiple platforms

    In many large organizations, users are running Office on a variety of supported platforms. For more information about these issues, see the Microsoft Office 97 Resource Kit.

Selecting Office Standard Features

The workgroup features in Office establish how your users will communicate and work together. By reviewing the Office feature set, you can determine how to configure clients for the needs of your users. Because you can choose which Office components to install, you have a lot of flexibility in tailoring client installations to include the best set of features for your users, while reducing disk space usage.

The Microsoft Office 97 Resource Kit provides detailed information on the workgroup features available in Office 97.

Determining Configuration and Installation Options

When you understand the variables in your organization and how they will affect the manner in which you deploy Office, you can decide how to configure the preferred client. You will make decisions in the following areas:

Location of Office files

When deciding where to place Office files, consider how the client will be used and evaluate the benefits of each placement option, including how each option will affect your ability to support these configurations in the future. Office can be local (files installed on the client's hard disk) or shared (files are located on a network server, and users share those files over the network). You can also put some files on the local hard disk and some files on the server. Tools in the Microsoft Office 97 Resource Kit let you specify which drive on the client computers will be used for the installation.

Installation options

Several basic installation options are available in the Office Setup program when Office Setup is run interactively by the user. You can also create customized options if the Office Setup program is to be run in batch mode using a customized script.

Installation method

Three methods can be used to perform the installation on the clients:

  • Interactive — allows the user to make all installation decisions.
  • Batch — provides a preset installation script for the user.
  • Push — initiates the installation for the user without user intervention.

A complete discussion of all these options can be found in the Microsoft Office 97 Resource Kit.


Preparing the Clients

When forming your target machine groups, run queries to make sure that each client has enough hard disk space, RAM, and processing capability to run Office. The requirements are outlined in the following table:

To install | you need this much hard disk space
Microsoft Office Standard |
Typical installation | 102 MB
Custom installation | 67 MB (minimum) to 167 MB (maximum)
Microsoft Office Professional |
Typical installation | 121 MB
Custom installation | 73 MB (minimum) to 191 MB(maximum)

Note The SMS inventory records disk space on a per-drive basis, not on a per-computer basis. If the client computers in your organization typically use a small C: partition and a larger D: partition for application and data files, check for disk space on the D: drive.

To find the computers that are ready for Office 97, you can use a query similar to the following:

[QDF]

Version=1.0

[Query Definition]

Name=Ready for Office 97

Comment=

Architecture=Personal Computer

[Rule 1]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Service Pack Version

Operator=9

Value=Service Pack 5

[Query]

Query Rule Part 1=(

Query Rule Part 2=(

Query Rule Part 3=(

Query Rule Part 4=Rule 1

Query Rule Part 5=AND

Query Rule Part 6=Rule 2

Query Rule Part 7=AND

Query Rule Part 8=Rule 3

Query Rule Part 9=)

Query Rule Part 10=OR

Query Rule Part 11=(

Query Rule Part 12=Rule 4

Query Rule Part 13=AND

Query Rule Part 14=Rule 5

Query Rule Part 15=)

Query Rule Part 16=OR

Query Rule Part 17=Rule 6

Query Rule Part 18=)

Query Rule Part 19=AND

Query Rule Part 20=(

Query Rule Part 21=Rule 7

Query Rule Part 22=OR

Query Rule Part 23=Rule 8

Query Rule Part 24=)

Query Rule Part 25=)

Query Rule Part 26=AND

Query Rule Part 27=Rule 9

[Rule 2]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Version

Operator=9

Value=3.51

[Rule 3]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Operating System Name

Operator=9

Value=Microsoft Windows NT

[Rule 4]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Operating System Name

Operator=9

Value=Microsoft Windows NT

[Rule 5]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Version

Operator=9

Value=4.0

[Rule 6]

AGroup=MICROSOFT|OPERATING_SYSTEM|1.0

Attribute=Operating System Name

Operator=9

Value=MS Windows 95

[Rule 7]

AGroup=MICROSOFT|PROCESSOR|1.0

Attribute=Processor Name

Operator=15

Value=486

[Rule 8]

AGroup=MICROSOFT|PROCESSOR|1.0

Attribute=Processor Name

Operator=15

Value=PENTIUM

[Rule 9]

AGroup=MICROSOFT|DISK|1.0

Attribute=Free Storage (MByte)

Operator=5

Value=150

[Last Modified]

Date=01-28-97

Time=17:51:26

This query is available in the folder SMS\Queries on the BackOffice Resource Kit CD-ROM.

Before installing Office, run virus-detection, disk-scanning, and defragmentation programs on the client computers. Although the computer may appear to be operating properly, software upgrades often uncover hardware or software problems because of the way they read and write data to the hard disk. Checking the computer before installing Office will help you stay focused on issues related to the installation process.

Be sure to back up critical data and configuration files for the client, in case the installation fails or you need to revert to the old system for some reason. Also, you should create a Microsoft diagnostics report and copy it to a floppy disk by running MSD.EXE on the hard disk. If you will need to restore automatically, consider using a commercial backup program, instead of copying the files by hand.

Any or all of the following can be used with Office; however, they are
not required:

  • For workgroup functionality and WordMail, your networking software must be Windows-compatible.
  • 2400-baud or higher modem (9600-baud modem recommended).
  • Audio board with headphones or speaker.


Creating the Administrative Installation Server Share

To install Office over the network, first create a network installation server share by performing an administrative setup of Office, using the setup /a command, from the Office Installation CD-ROM.

Note Installations over the network should always be done from an administrative share, never from the CD-ROM. Installation over the network with the CD-ROM as a source directory is neither advised nor supported.

For more information about creating the administrative installation point, see Chapter 4, "Installing Microsoft Office," in the Microsoft Office 97 Resource Kit.

SMS compresses the Office files before copying the package to distribution servers. While SMS is preparing the files for distribution, it requires about three times the disk space of the office folder. For example, the files for Office 97 Professional fill approximately 325 MB, so you need an additional 1,000 MB (1GB) of free disk space to perform the compression.

The SMS drive on the computer on which you create the package must have disk space available as shown in the following table:

For these files | Allow this much space for Typical installation | Allow this much space for fully customized installation
uncompressed MSOffice files created by administrative setup | 273 MB | 640 MB
two copies of compressed source files | 271 MB | 829.2 MB
temporary file used during compression and decompression | 273 MB | 640 MB
Total | 817 MB | 2109.2 MB

In either case, the MSAPPS folder requires another 50.2 MB, which compresses to 28.8 MB. You will need this folder if you will be sharing MSAPPS components over the network.

In addition, each distribution server must have 273 MB of disk space available for the distribution copy of the package for a Typical installation, or up to 640 MB for a fully customized copy.

Using Administrative Setup

Use the administrative setup command to build a source directory.

To prepare the administrative installation point

Choose the location for the administrative installation point.

Make sure that there is sufficient disk space on the server for the source files.

Make sure that all folders are empty.

If a previous version of Office exists, move any custom templates you want to save, then delete all of the Office files.

You need read, write, delete, and create permissions to use these folders while doing the administrative installation.

Lock all folders to prevent network user access during the administrative installation.

Disable virus-detection software to prevent erroneous virus-detection triggers while Setup is running.

Make sure the client on which you will be running SETUP.EXE is using Windows 95, or Windows NT 3.51 or later.

Use the following command to start setup:

setup /a

This command copies the source files into a directory and creates an .STF file (OFF97PRO.STF for Office Professional Edition or OFF97STD.STF for Office Standard Edition) for use in network installations.

Important Do not use the .STF file located on the installation disks for a network or customized installation.

Sharing MSAPPS Components

When you create an administrative installation point, you define where the shared MSAPPS folder will be placed on the network; this location is written into the .STF file. When Office is installed to run shared components from this MSAPPS folder, the MSAPPS location defined in the .STF file is written into the user's Registry.

SMS will distribute the Office installation package to the distribution server that is defined for a particular client, but it will not change the shared MSAPPS location defined in the .STF file. This means that even though a particular package may be sent to multiple distribution servers, all users of that package will share the same MSAPPS network location definition.

If you want different groups of users to share different MSAPPS folders, you first need to place copies of the MSAPPS folder on the servers you want to use for this purpose. You can do this by importing the MSAPPS.PDF file from the Microsoft Office 97 Resource Kit and running it as a Share Job on Server job. Edit the .STF file after it has been distributed to each server, as described in the Microsoft Office 97 Resource Kit, to make sure that the .STF file points to the server that the share is currently on.

Once you have the MSAPPS folder on different servers, you can give users access to the appropriate MSAPPS location in one of two ways: using drive-letter mapping and creating one SMS package, or using UNC paths and creating multiple packages.

Note During administrative setup, two MSAPPS folders are created. One, located within the MSOffice folder, is used when all Office components are installed on the client computers. The other, on the same level as the MSOffice folder, is maintained on the distribution server and is used when you install Office to use shared MSApps components.

Drive-Letter Mapping

By mapping the same drive letter on every user system to the appropriate MSAPPS server, you need only one SMS package for all users.

To use drive-letter mapping to define multiple MSAPPS locations

During administrative setup (setup /a) of Office, specify the location of MSAPPS to be a certain drive letter—for example, drive H.

Import the MSAPPS97.PDF, selecting the Sharing section of the PDF and pointing to the MSAPPS administrative share.

On each client, map the drive letter you specified in Step 1 to the server containing the MSAPPS folder appropriate for that client. You can use a logon script to assign the drive-letter mapping.

Create a single SMS package for Office using the administrative installation point you created.

For information about creating this package, see the next section, "Creating the Office Package."

Distribute this package to all clients.

When Office is installed using the package, Office Setup will define the drive letter you specified to be the location of the MSAPPS folder, and that drive letter will be mapped to the server appropriate for each client.

If you want to use drive-letter mapping, but cannot define a single drive letter for all clients and all MSAPPS servers, create one SMS package and edit the .STF file for each MSAPPS location. The procedures for doing so are described in the following section, "UNC Paths."

UNC Paths

If you are using UNC paths to specify the location of the MSAPPS folder, create one SMS package and edit the .STF file for each MSAPPS location. This method is also used if you are using drive letters but cannot define a single drive letter for all clients and all MSAPPS servers.

Perform one administrative installation and make multiple copies of the .STF file, one for each MSAPPS location. The location of the MSAPPS folder is defined in the .STF file when you do the administrative installation. By using the Network Installation Wizard, you can modify the MSAPPS definition in each .STF file to point to a different network location.

To use multiple .STF files to define multiple MSAPPS locations

Run administrative setup (setup /a) for Office.

Copy the MSAPPS folder, and all subfolders, to multiple servers.

Make copies of the .STF file (found in the MSOffice folder) — one copy for each MSAPPS location.

Run the Network Installation Wizard on each .STF file.

In the dialog box in which you define the location of the MSAPPS folder, specify for each .STF file a different MSAPPS location.

Copy one of these .STF files to the MSOffice folder.

Create an SMS package for Office using the MSOffice folder.

For more information, see the next section, "Creating the Office Package."

Create a job to send this package to the distribution servers.

Either copy the appropriate .STF file to each distribution server after distribution is completed, or edit the .STF file on the distribution server.


Creating the Office Package

When using the SMS program group control to install Office 97, use the PDF files in the Microsoft Office 97 Resource Kit, rather than those included with Office 97. The PDF files in the Microsoft Office 97 Resource Kit support program group control, while the PDFs on the Office 97 CD-ROM do not. If you will be using Program Control Manager to install local copies of Office on client computers, use the PDF files on either the Office 97 CD-ROM or those in the Microsoft Office 97 Resource Kit.

Eight PDF files are included in the Microsoft Office 97 Resource Kit Tools and Utilities:

This PDF | is used for installing
Off97pro.pdf | Office 97 Professional Edition
Off97std.pdf | Office 97 Standard Edition
MSAPPS97.pdf | Office 97 shared components (available with the Microsoft Office 97 Resource Kit only)
Excel97.pdf | Microsoft Excel 97 stand-alone
Outl97.pdf | Microsoft Outlook 97 stand-alone
Pptsms97.pdf | Microsoft PowerPoint 97 stand-alone
Work97.pdf | Microsoft Word 97 stand-alone
Clipart.pdf | Microsoft Office 97 Clip Gallery

Be sure there is enough room on your distribution servers for the Office 97 package.

To import the package

In SMS Administrator, open the Packages window. From the File menu, choose New.

The Package Properties dialog box appears.

Choose Import.

The File Browser dialog box appears.

Select the PDF you want to use, and click OK.

Choose Workstations.

The Setup Package for Workstations dialog box appears.

In the Source directory box, type the location of the package source directory and click Close.

If you choose to browse through the list of files, edit the resulting path so that it shows the UNC name (which would begin with \\servername\sharename) rather than the relative name (which would begin with the drive letter you have assigned to the server during the current session).

Click OK in all open dialog boxes.

The Office PDFs include the following package options:

Typical

Setup runs in batch mode, installing Office with a Typical installation. For this option, use the command

setup.exe /Q1 /B1

Custom

Setup runs in batch mode, installing Office with a Custom installation. Use this if you have modified the .STF file. If you do not modify the .STF file, Custom installation run in batch mode is identical to Typical installation.

For this option, use the command

setup.exe /Q1 /B2

Uninstall

Setup runs in batch mode, removing Office from the client computer. For this option, use the command

setup.exe /Q1 /U

Manual

Setup runs interactively. If you want users to run Setup interactively, modify the Manual package command to add a /B1 or /B2 command-line option to select a Typical or Custom installation by default.

If you use the Manual package option, users can select a Run from Network Server installation. In order for the Package Command Manager to support a Run from Network Server installation, you must use the Network Installation Wizard included with the Microsoft Office 97 Resource Kit, and then manually edit the .STF file on each distribution server before the package is offered to any clients. If you have not taken these steps, users should be strongly discouraged from selecting a Run from Network Server installation.

For this option, use a command of the form

setup.exe /Bx

where /B1 specifies a typical installation and /B2 specifies a Custom installation.

In these commands, the /Q1 option directs Setup to run with no user interaction, and the /Bx option specifies the installation type.

To add custom commands to the Office PDF

In the SMS Administrator, open the Packages window, and from the File menu, choose New.

The Package Properties dialog box appears.

Choose Import.

The File Browser dialog box appears.

Select the appropriate PDF.

Click OK.

Choose Workstation if you want to install Office on the client's hard disk.

The Setup Package dialog box appears.

Specify the location of the administrative installation point for Office as the source folder.

To define the new command line, choose New.

In the Command Name box, type a name for the new command.

In the Command Line box, type the command to run your custom
Office Setup.

For example, to run SETUP.EXE from the administrative installation point in batch mode, creating a log file, type:

setup.exe /qt /g "setuplog.txt"

To indicate that no user input is required to run the package, select the Automated Command Line check box.

In the Supported Platforms box, select the appropriate platforms: Windows 95, Windows NT, or both.

Click OK, and then click Close.


Installing Office Remotely

Office 97 permits a Run from Network Server installation. Use the Program Group Control, rather than the Package Command Manager, to distribute a Run from Network Server installation to the clients. Program Group Control provides fault tolerance and load balancing, while Package Command Manager does not.

You will need to complete the following tasks:

  • Create a package for the main Office components.
  • Create a package for the shared Office components.
  • Create a Share Package On Server job for each package.
  • After the jobs have completed, create a program group containing the two packages, and assign it to the users.
  • Users install Office on their computers the next time they log on, or by using Program Group Control from the SMS folder.

To create a package for the main Office components

In the SMS Administrator, open the Packages window, and from the File menu, choose New. The Package Properties dialog box appears.

Choose Import. The File Browser dialog box appears.

Select the appropriate PDF (OFF97STD.PDF or OFF97PRO.PDF) from the Microsoft Office 97 Resource Kit Tools and Utilities.

Choose Sharing. The Source Directory dialog box appears.

Enter the location of the main Office files (for example, \\system1\install\msoffice) and click Close.

Click OK to create the package.

To create a package for the shared Office components

In the SMS Administrator, open the Packages window, and from the File menu, choose New. The Package Properties dialog box appears.

Choose Import. The File Browser dialog box appears.

Select MSAPPS97.pdf from the Microsoft Office 97 Resource Kit Tools and Utilities.

Choose Sharing. The Source Directory dialog box appears.

Enter the location of the main Office files (for example, \\system1\install\msapps) and click Close.

Click OK to create the package.

To create a job to distribute the main Office components

In the SMS Administrator, open the Jobs window, and from the File menu, choose New. The Job Properties dialog box appears.

In the Job Type box, select Share Package on Server.

Click Details. The Job Details dialog box appears.

Select the main Office package (for example, Microsoft Office 97 Professional 8.0) in the Package box.

Under Job Target, select a site or site group that includes the users you want to receive this job.

Click OK.

To create a job to distribute the shared Office components

In the SMS Administrator, open the Jobs window, and from the File menu, choose New. The Job Properties dialog box appears.

In the Job Type box, select Share Package on Server.

Click Details. The Job Details dialog box appears.

Select the shared Office package (for example, MSAPPS97) in the Package box.

Under Job Target, select a site or site group that includes the users you want to receive this job.

Click OK.

After both of these jobs are complete, create a program group for users to install Office.

To create a program group for installing Office

In the SMS Administrator, open the Program Groups window, and from the File menu, choose New. The Program Group Properties dialog box appears.

In the Name box, type a name for the program group (for example, Office Installation).

Choose Packages.

From the Available Packages list, select both of the Office packages you have created (the main components and shared components). Click Add to add both packages to the Member Packages list.

Choose OK.

Choose User Groups.

From the Don't Share with these Groups list, select the group or groups that you want to have access to the program group. Then click Add to move the groups to the Share with these Groups list.

Click OK twice to create the program group.

Now users can install Office on their computers, using the following procedure:

To install Office on client computers, using Program Group Control

At the client computer running Windows 95 or Windows NT 4.0, click Start, point to Programs, point to SMS Client folder, and then click Program Group Control. SMS Program Group Control adds a folder with the name of the program group you created to the Programs folder in the Start menu.

If the client computer is running Windows NT Workstation 3.51, go to Program Manager, double-click the SMS Client program group, and double-click Program Group Control. Program Group Control adds a program group that includes an item with the name of the program you created to Program Manager.

Click Start, point to Programs, point to the new program group, and click the Setup item (for example, MS Office 97 Pro Installation).

If the client computer is running Windows NT Workstation 3.51, go to the Program Manager and double-click New Program Group, then double-click the Setup command name (for example, MS Office 97 Pro Installation). The Program Group Control adds a program icon with the name of the program group you created (for example Office Installation) to the Program Manager.

The Program Group Control Start dialog box appears, asking if the applications should be configured now.

Click Yes to start Office Setup.

After Setup is complete, a new folder for the Office 97 will be added to Programs in the Start menu. (If the client computer is running Windows NT Workstation 3.51, an Office 97 program group is added to Program Manager). Users can start applications by clicking items in the new folder or program group, just as they would if Office 97 were installed on the local computer.


After Deployment

After the package has been distributed to all servers, you can delete the compressed files for the package from the following folders:

  • sms\site.srv\sender.box\tosend
  • sms\site.srv\despoolr.box\store

The names of the compressed files for a package all begin with the package ID number.

After the job status for distributing Office 97 changes to Complete, make sure the new software has been successfully installed on the client computers. To do so, you can use the following SMS Software Audit query:

[QDF]

Version=1.0

[Query Definition]

Name=MS Office 97 Pro Installation Present

Comment=

Architecture=Personal Computer

[Rule 1]

AGroup=MICROSOFT|SOFTWARE|1.0

Attribute=Software Name

Operator=9

Value=Microsoft Office 97 Professional 8.0

[Query]

Query Rule Part 1=Rule 1

[Last Modified]

Date=01-22-97

Time=14:57:31


Chapter 2 - Working with Systems Management Server

This chapter provides tips for working with SMS. The following topics are discussed:

  • Unattended installation of new clients
  • PCM service for SMS 1.2 clients
  • Controlling package share partitions
  • Interpreting SNMP traps
  • SMS Registry Reference


Unattended Installation of SMS Client

SMS client software typically is automatically installed via a logon script when a user logs on from a client computer. You can also install SMS client on a computer running Windows NT Workstation or Windows NT Server without anyone logging on at that computer. This involves using tools from both the Windows NT Server Resource Kit and the BackOffice Resource Kit.

The instructions in this section assume that the SMS logon server to be used by that client is already set up. You will need a licensed copy of both the Windows NT Server Resource Kit and the BackOffice Resource Kit to use the tools described in this section.

The computer that will receive the unattended installation of the SMS client must have the Remote Command Server service (RCMDSVC.EXE) installed. This service is included in the Windows NT Server Resource Kit, and is documented in the on-line Help for that Resource Kit.

If necessary, you can install the Remote Command Server remotely, using the RSERVICE utility. RSERVICE is included with this Resource Kit, and is documented in the on-line Help.

To install Remote Command Server using RSERVICE

Create an initialization file to install Remote Command Server. The RSERVICE initialization file contains the name of the domain and information on how to determine the computers where RCMDSVC.EXE is to be installed. This file is an ASCII text file that follows the standard Windows INI file format. Sections in this initialization file are required to give the service name and other information about the service. An example initialization file for Remote Command Server installation is given here for a domain named EC_SALES.

[domain name]

;specify domain and computers affected by this initialization file

;domain_name=parameter

EC_SALES=NTWD

[service account]

;specify user account that the service is to use, including domain

;*=domain_name\account_name

*=HQ_MASTER\SMS_RCMD

[service name]

;specify the service (for PCM service, type exactly as shown)

*=Remote Command Server

[executable file]

;specify the executable file (for PCM service, type exactly as shown)

*=RCMDSVC.EXE

[installation directory]

;specify where the service is to be installed on the destination computers

;*=drive:\[path]

*=c:\sms_rcmd

[source directory]

; specify the location of the service executable files on the local computer

;*=drive:\[path]

*=d:\sms12\site.srv\x86.bin

This example initialization file could be used to install the Remote Command Server onto all Windows NT Workstation computers (NTWD) in the EC_SALES domain. You could specify other classes of computers, as follows:

Parameter | Computers specified
NTWD | all Windows NT Workstation computers
NTSD | all stand-alone servers
NTPDC | primary domain controller
NTBDC | all backup domain controllers

You can install the service on multiple classes of computers by listing the parameters in a comma-separated list.

Save this initialization file with an appropriate filename; for example, EC_SALES_RCMDSVC.INI.

Create the user account that is referenced in the [service account] section of the RSERVICE initialization file, if it does not exist already. This account should have admin privileges on the client computers.

Log on to an SMS site server that has network access to the domain specified in the initialization file.

Install the Remote Command Server on the computers referenced in the [domain name] section of the initialization file. If you are logged on using the user account you established for RSERVICE, use the following command-line:

RSERVICE /INSTALL initialization_filename

If you are logged on using any other user account, use the /c option for the RSERVICE command, as follows:

RSERVICE /INSTALL initialization_filename /c

The /c option will cause RSERVICE to prompt you for the password of the account specified in the initialization file. If the /c is not in the command line, RSERVICE will attempt to use the user account from which the RSERVICE command is issued, and you will receive an "Access Denied" message.

Once the Remote Command Server is installed on the target computer, you can use Remote Command (RCMD.EXE), from any computer on the network that has the Windows NT Server Resource Kit installed, to install the SMS client.

To install the SMS Client using Remote Command

The target computer should be turned on. For example, you can have users leave their computers on after logging off.

At any computer on the network that has Windows NT Server Resource Kit installed, type the following command:

rcmd \\target_computer

where target_computer is the name of the computer on which you want to install the SMS Client.

An RCMD console window will open on your screen. Any commands entered in this window are issued for the target computer.

In the RCMD console window, enter the following command:

net use x: \\SMS_logon_server\sms_shr

where x is any available drive letter and sms_logon_server is the server that the target computer can use as an SMS logon server.

In the RCMD console window, enter the following command:

run x:\runsms.bat

where x is the drive letter used to connect to the SMS logon server in Step 3.

Since the RUNSMS.BAT command is effectively issued from the target computer, all the SMS client files are installed on that computer. During this time the RCMD console window will display the words "SYSTEMS MANAGEMENT SERVER."

Still using the RCMD console window, you may edit c:\SMS.INI on the target computer to set the remote troubleshooting features.

In the RCMD console window, use the following Windows NT Server Resource Kit command to shut down and restart the target computer:

shutdown \\target_computer

where target_computer is the computer on which you have just installed the SMS Client.

You can verify that the SMS client software has been installed by looking for the target computer in the SMS inventory. Several variables affect how long it takes for the computer to be added to the inventory, including the service response time set for the SMS server, the network load, the load on the SMS server, and how often the target computer is logged on.


PCM Service for SMS 1.2 Clients Running Windows NT

In the past, the Package Control Manager (PCM) has been installed as a service on SMS logon servers, but only as an application on SMS clients. Because the client version runs as an application, it has only the privileges assigned to the user account from which the application is run.

PCM can now be installed as a service on any Windows NT workstation or Windows NT stand-alone server (x86 or Alpha) that is a member of a Windows NT domain and is an SMS 1.2 client. The executable file for the new PCM service is PCMSVC32.EXE. In addition to the new PCMSVC32.EXE file, the executable file for the PCM application (PCMWIN32.EXE) has been changed and will need to be replaced on the client computers.

These two files are included with the PCM service deliverable. A copy of RSERVICE.exe is also included, since it is used to install the PCM service. All three executables will also be available in SMS Service Pack 2, along with other enhancements and bug fixes.

The PCM service requires a user account that has the following privileges:

  • Administrator privileges on the client computer
  • Domain user authority to read a PCM instruction file on the SMS logon server and to execute a setup program in the package directory on the SMS distribution server

Because it works through a user account with administrative privileges, the PCM service can perform tasks that the PCM application cannot. For example, it can install files into secured directories or make changes to secured registry keys.

However, the existence of the privileged account used by the PCM service introduces a security risk that administrators must consider carefully before installing the PCM service. The privileged account must either be a member of the Domain Users global user group, and be assigned to the administrator local group on each computer to be administered, or it must be made a member of the Domain Admins global group for the domain.

This can open up a potential security risk in your network. If users on any of these workstations were able to replace the PCMSVC32.EXE file with their own service applications, they would then be able to run any application they wanted in a domain admin security context. For example, if a Domain Admin account were used, the substituted application could grant a user's regular user account full Domain Admin privileges. The user would then have not only administrative access to all domain resources, but also administrative access to all workstations. To maintain security, the directory containing PCMSVC32.EXE must be carefully protected, and users must not have admin access to their machine.

Note If several automated background jobs are set for same mandatory time, the PCM service will create an instruction (INS) file entry for only one of those jobs, so only that job will be run. To ensure that an INS file entry is made for each job, so that they all are run, assign different mandatory times for the jobs.


Installing the PCM Service on SMS 1.2 Clients

You can install the PCM service on any Windows NT workstation or Windows NT stand-alone server (x86 or Alpha) that is a member of a Windows NT domain and is an SMS 1.2 client. The PCM service cannot be installed on workstations that are members of a workgroup, rather than a domain.

Most of the work involved in installing the PCM service can be done automatically, using the RSERVICE utility (Remote Service Utility). In addition, RSERVICE can be used to start, stop, or query the status of the service whenever necessary, thereby simplifying the management of the PCM service on all Windows NT computers in a single domain. In fact, RSERVICE can be used to control any service on multiple computers within a domain. The control options include installing, starting, stopping, removing, querying the status of, and pausing a service, or sending a control code to a service.

The RSERVICE utility is a console application. The data required to control a service using RSERVICE must be supplied in an initialization file. Once the initialization file has been created, the service can be controlled with a single command line. The RSERVICE utility is documented in the online Help for the SMS Resource Kit. Specific information for creating an initialization file for the PCM service is provided in the following section. RSERVICE is documented in the online Help for the BackOffice Resource Kit, and in Chapter 4, "Tools," in this Guide.

The following steps are required to install the PCM service:

  • Establish the user account to be used by the PCM service.
    • Make sure that account is included in the Domain Admins group, or add the account to the Local Admins group on each client computer.
    • If the account is included in the Domain Admins group, make sure the Domain Admins global user group has administrative authority on the Windows NT Workstation and stand-alone computers in the domain.
  • Create an initialization file that RSERVICE can use to install and manage the PCM service.
  • Install the modified PCM application file on the client computers.
  • Use the RSERVICE initialization file to install the PCM service.
  • Enable logging to trace events generated by the PCM service.


Establish the User Account to be Used by the PCM Service

In addition to creating the initialization file, you must do the following:

Create a domain user account that the PCM service will use. Log on as a domain administrator and open User Manager for Domains to create the account.

While still in User Manager for Domains, add the user account to the Domain Admins global user group.

Ensure that the Domain Admins global user has administrative authority on the Windows NT Workstation computers in the domain. By default, Windows NT computers grant Local Admins group membership to the Domain Admins global group. If this default behavior has been changed on computers in your organization, you may need to manually add the account designated for the PCM service to the local administrators group on those computers. The account used by the PCM service must also have "Log on as a Service" privilege on the local computer.


Create the RSERVICE Initialization File

The RSERVICE initialization file contains the name of the domain and information on how to determine the computers on which PCM Service is to be installed. This file is an ASCII text file that follows the standard Windows INI file format. Sections in this initialization file are required to give the service name and other information about the service. An example initialization file for PCM Service installation is given here for a domain named EC_SALES.

[domain name]

;specify domain and computers affected by this initialization file

;domain_name=parameter

EC_SALES=NTWD

[service account]

;specify user account that the service is to use, including domain

;*=domain_name\account_name

*=HQ_MASTER\SMS_PCMSVC

[service name]

;specify the service (for PCM service, type exactly as shown)

*=SMS_PACKAGE_COMMAND_MANAGER_NT

[executable file]

;specify the executable file (for PCM service, type exactly as shown)

*=pcmsvc32.exe

[installation directory]

;specify where the service is to be installed on the destination computers

;*=drive:\[path]

*=c:\sms_pcm

[source directory]

; specify the location of the service executable files on the local computer

;*=drive:\[path]

*=d:\sms12\site.srv\x86.bin

This example initialization file could be used to install PCM service onto all Windows NT Workstation computers (NTWD) in the EC_SALES domain. You could specify other classes of computers, as follows:

Parameter | Computers specified
NTSD | all stand-alone servers
NTPDC | primary domain controller
NTBDC | all backup domain controllers

You can install the PCM service on multiple classes of computers by listing the parameters in a comma-separated list.

Note You can install the PCM service on domain controllers only if they are SMS 1.2 clients and are not being used as SMS logon servers.

Save this initialization file with an appropriate filename; for example, EC_SALES_PCMSVC.INI.


Install the Modified PCM Application on Client Computers

The PCM service normally will not run jobs while the PCM application is running. To ensure that the PCM application is not running, either disable (or remove) the PCM application, or make sure that no user is logged on. To disable the application, use the Windows NT 4.0 Task Manager.

Any packages sent to SMS 1.2 clients with the package properties Automated and System (Background) Task need to be performed by the PCM service rather than by the PCM application. To avoid problems that could arise if the PCM application attempts to execute a job intended for execution by the PCM service, a modified version of PCMWIN32.EXE (the PCM application executable file) is now available from Product Support Services (PSS). The modified PCM application will not attempt to run jobs that are Mandatory and that have the package properties Automated and System (Background) Task. Such jobs will wait. When the user has logged off and the PCM service sees the ready job upon its next polling cycle, these jobs will be run by PCM service, instead. Remember that once the PCM application is launched, it continues to run until the user logs off, or until the process is stopped using the Windows NT Task Manager. Choosing Close from the File menu merely hides the PCM application; it doesn't end it.

The new version of PCMWIN32.EXE should be installed before the PCM service is deployed, as described in the following procedure.

To install the modified PCMWIN32.EXE

Go to the source directory on the site server, and overwrite the source PCMWIN32.EXE file with the new PCMWIN32.EXE file. The old file will be in the subdirectory \site.srv\maincfg.box\client.src\platform.bin, where platform.bin is either x86.bin or alpha.bin.

Change the date and time on the file SYSTEM.MAP (in the main SMS installation directory) to the current date. Several utility programs are available in the public domain to do this. One simple way is to edit the file in Notepad and then save it (while being careful not to change the file's contents.) The file must be saved in ASCII format.

Maintenance Manager will then create a new copy list that includes the new version of PCMWIN32.EXE; distribute the new PCMWIN32.EXE to all SMS logon servers in the site; and update the copy-list version number in the copy-list files. The first time a client runs the SMS logon script after the logon servers are updated, the new copy list will be detected, and the new PCMWIN32.EXE will be copied to the client.


Use the RSERVICE Utility to Install the PCM Service

Once the user account and the initialization file have been prepared, you are ready to test the file and then install the PCM service.

Note As always when modifying large numbers of computers with a single remote command, it is best to test the process before changing your organization's production environment. The specification of destination computers in the initialization file cannot be tested, of course. However, you can still test that the remainder of the initialization file has been set up correctly, that the required source files are accessible, that the user account specified for the PCM service has the necessary privileges, and that the PCM service itself serves the needs of your organization.

You can test the initialization file either by using the /M option with the RSERVICE command (so that you are only affecting a single computer), or by creating a different version of the RSERVICE initialization file that specifies a different set of computers.

To install the PCM service on the computers specified in the initialization file, run the RSERVICE utility once on an SMS site server that has network access to the domain. If you are logged on using the user account you established for RSERVICE, use the following command-line:

RSERVICE /INSTALL initialization_filename

If you are logged on using any other user account, use the /c option with the RSERVICE command, as follows:

RSERVICE /INSTALL initialization_filename /c

The /c option will cause RSERVICE to install PCM using the account specified in the initialization file. If the /c is not in the command line, RSERVICE will attempt to use the user account from which the RSERVICE command is issued, and you may get an "error 5(Access Denied)" message. Regardless of the /c command line switch, you will be prompted to enter a password for the service account under which the PCM service will run.

Note RSERVICE installs services with a default startup mode of Manual. This means that after a reboot, such as occurs when upgrading the operating system, the PCM service will not be automatically restarted, and jobs normally executed by the PCM service will not be run until it is. You can use RSERVICE to start the service on a particular computer or on groups of computers.

If the initialization file is not found (for example, if the file name is mistyped or if the file is not in the current or specified directory), RSERVICE will return a message saying that no domain is specified in the [domain name] section of the initialization file. If you receive this message and you are sure that a domain is correctly specified in the file, make sure the file name has been specified correctly in the RSERVICE command.

For example:

RSERVICE /INSTALL EC_SALES_PCMSVC.INI

or

RSERVICE /INSTALL EC_SALES_PCMSVC.INI /c

In this example, the RSERVICE utility then creates a directory called C:\SMS_PCM on all Windows NT Workstation computers in the domain EC_SALES. It then copies file PCMSVC32.EXE from directory D:\SMS12\SITE.SRV\X86.BIN on the local computer (which is a site server) to the directory C:\SMS_PCM on all of these computers. Finally, it installs the service SMS_PACKAGE_COMMAND_MANAGER_NT with an executable file of C:\SMS_PCM\PCMSVC32.EXE and a user account of HQ_MASTER\SMS_PCMSVC.

Note If RSERVICE will attempt to configure a drive connection to a computer, and you currently have one or more drive connections to that computer, RSERVICE may be unable to connect using the account specified in the INI file. This is because the same user cannot make more than one connection to the same system using different account credentials. If this happens, verbose output from RSERVICE includes a "1219" message code. (For verbose output, include the /v switch with the RSERVICE command.) To avoid the problem, log on using the account established for RSERVICE.


Use RSERVICE To Control The PCM Service

In SMS 1.2, the PCM service can be used to execute mandatory and automated system task jobs. Per-user settings cannot be configured with the PCM service.

After the PCM service has been installed on the destination computers, you can use the RSERVICE utility and the initialization file you created to start the service on those computers from the site server. The command is of the form:

RSERVICE /start initialization_filename

In this example, the service could be started on all the Windows NT Workstation computers in the EC_SALES domain with the command:

RSERVICE /START EC_SALES_PCMSVC.INI

If you want to remove the service, you can use the command:

RSERVICE /DEINSTALL /L EC_SALES_PCMSVC.INI

The DEINSTALL functionality fails unless the log file switch /L is also used.

Other commands are available to control the service. For more information, see the SMS Tools Help in this Resource Kit.

Note Under certain conditions, RSERVICE may report that it cannot stop or cannot start the service when it has actually succeeded. In this case, verbose output using the /V switch indicates that a WNetAddConnection2() returned error 87. This error can be ignored. If you want to make sure the service has been stopped or started, use SMS Admin to look at the properties for the client computer, run Server Manager on the client computer, and examine the status of the individual service.


Enable Logging

For the PCM service to log trace messages, the TRACING registry key and Enabled value must be added to the registry of the client computer, as follows:

HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\SMS

\TRACING

Enabled 0x00000001

In addition, the following registry setting is needed to construct the proper path to the log file to be used by the PCM Service:

HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\SMS

\IDENTIFICATION

"Installation Directory" "C:\MS\SMS" (data type REG_SZ)

Note There is a space between Installation and Directory.

Also, the SMS_PACKAGE_COMMAND_MANAGER_NT key must be created, with the Enabled and TraceFilename values set as follows:

HKEY_LOCAL_MACHINE

\SOFTWARE

\Microsoft

\SMS

\TRACING

\SMS_PACKAGE_COMMAND_MANAGER_NT

Enabled 0x00000001

TraceFilename \MS\SMS\LOGS\pacman.log (data type REG_SZ)

After these changes have been made, restart SMS_PACKAGE_COMMAND_MANAGER_NT so it reads and uses the new settings. Because the change must be made manually at the client computer, you may prefer to enable logging on only to those computers on which you encounter problems with jobs run by the PCM service.


Special Cases

Microsoft has tested the use of PCM service for installing several applications and operating systems. Clean installations were tested, as well as upgrades. The tests used client computers running Windows NT Workstation and Windows NT Server, version 3.51 with Service Pack 5 and version 4.0 with Service Pack 1.

This section provides you with special-case information gathered in these tests.

Installing Office 95 on Computers Running Windows NT

For both Windows NT Workstation and Windows NT Server, versions 3.51 and 4.0, the files for Office 95 are installed correctly by the PCM service. While Office 95 is being installed, it makes no difference which account is logged on at the computer, or even whether anyone is logged on at all. Job status usually remains Active even after the job is completed, although in some cases it correctly changes to complete.

If the computer is running Windows NT 4.0, Office 95 items are not generally added to the Start menu.

If the computer is running Windows NT 3.51, no program groups or icons are created for Office 95.

In all cases, the Office 95 components work correctly when run from the executables (for example by double-clicking the MSACCESS.EXE file in File Manager or in Windows NT Explorer).

Installing Office 97 on Computers Running Windows NT

For both Windows NT Workstation and Windows NT Server, versions 3.51 and 4.0, the PCM service installs the files for Office 97 properly. While Office 97 is being installed, it makes no difference what account is logged in at the computer, or even whether anyone is logged in at all.

If the computer is running Windows NT 4.0, Start menu items are created as expected, and they apply to all accounts. However, if a new account is added after Office 97 is installed, that account will have two sets of Start menu items: one in the lower, common program groups section, and another in the upper, individual section. The items in the common section work properly. The items in the individual section do not work properly, and should be removed manually. (From the Start menu point to Settings, then choose Taskbar and go to the Start Menu Programs tab.)

If the computer is running Windows NT 3.51, no program groups or icons are created for Office 97.

In all cases, the Office 97 components work correctly when run from the executables (for example by double-clicking the MSACCESS.EXE file in File Manager or in Windows NT Explorer).

Upgrading From Office 95 to Office 97

In the PCM tests, Office 95 was first installed manually, to simulate the typical case in which the applications are already installed.

On Windows NT Workstation 4.0

The upgrade using the PCM service is fully functional. Items for Office 97 applications are added to the common Start menu. In addition, an account that already had Office 97 applications in its Start menu now has these items in both the lower, common portion of the Start menu and in the upper, individual portion of the Start menu. All of these items function properly.

Most Office 95 files are replaced with proxy files that invoke the equivalent Office 97 application when double-clicked. The Office 97 directory tree is fully populated, and the files there work correctly when double-clicked.

On Windows NT Workstation 3.51

The Office 97 directory tree is fully populated, and the files there work correctly when double-clicked, from any account. Most Office 95 files are replaced with proxy files that invoke the equivalent Office 97 application when double-clicked. However, no new program groups and icons are created for the Office 97 applications, and the old program groups and icons point to the Office 95 executable files. Since the Office 95 executable files have been replaced with proxy files, clicking the icons does not start the applications. To change the icon so that it points to the new files, select the icon and choose Properties from the File menu.

Upgrading Windows NT Operating Systems

The upgrade process works as usual when upgrading Windows NT Workstation 3.51 (Service Pack 4) to Windows NT Workstation 3.51 Service Pack 5, or from Windows NT Server 4.0 (no Service Pack) to Windows NT Server (Service Pack 1).

If you will be using the PCM service to upgrade from Windows NT 3.51 (Service Pack 5) to Windows NT 4.0, edit the command-line properties in the Windows NT upgrade PDF, replacing ntencap.exe /NTw with start. Because the NTENCAP.EXE program cannot detect a system reboot from a service, any job involving a reboot would fail to complete if you use NTENCAP. Therefore it should not be used with the PCM service.

Note When using PCM service to upgrade to Windows NT 4.0, there will be no detailed status report on the job. Also, the job may never be reported as Complete, even after it has completed successfully. This is because jobs that require a reboot may not provide PCMSVC32 enough time to write a complete status back to the logon server. In addition, if the PCMSVC32 polling interval is set to a value that is too fast, it may attempt to process an instruction a second time following the reboot, before the site has had time to process the completion of the first execution. This condition should correct itself in time, but can be prevented by keeping the PCMSVC32 polling interval set at one hour or more and the site response speed at "Fast" (the default.)


Controlling Package Share Drive Selection on Distribution Servers

When you create an SMS job to distribute a package, you must select the distribution servers that should receive the package (the distribution servers are specified in the Distribute Phase section in the Job Details dialog box). When the job activates and the package is sent to the site server at a specified site, SMS processes the package and instruction files, and determines how the package should be distributed to the specified distribution servers.

Two types of packages are distributed to distribution servers: Packages for Workstations and Packages for Sharing. When SMS distributes these packages, it always tries to ensure that the drive on which the package is placed has enough free disk space, and that the drive is formatted as NTFS. If either of these requirements are not met, SMS will look for another drive on which to install the package. SMS will not attempt to install the package if it cannot find a drive that has enough free disk space to hold the entire package.

When SMS is first installed at a site, it creates the Default Servers group and places the site server into this group. The Default Servers are used to receive all packages if no distribution servers are specified in a job. To reduce the load and conserve disk space on the site server, it is a good idea to specify other servers to be used in the Default Servers group, and to remove the site server from this group.


Setting the Minimum Free Disk Space

By default, SMS will not install a package onto a distribution server that has less than 100 MB free disk space. You can override this default by changing the SMS Drive Minimum Free Space in MBytes entry in the Site Server registry. You might want to override this default if the drives on your distribution servers are not particularly large. By changing the registry value from 100 MB to something like 10 MB, your distribution servers could store more packages.

To change the free space requirement

Open the registry to the following key:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Components\SMS_Despooler

Select the SMS Drive Minimum Free Space in Mbytes value entry. Specify the desired minimum value for free disk space on the distribution server SMS drive. The default is 100 MB (specified in hexadecimal as 0x64).


Packages for Workstations

Packages for Workstations are always placed into a subdirectory of the SMS_PKGx share. The SMS_PKGx share is created on distribution servers automatically by SMS; the x corresponds to the logical drive letter (for example, if the share is created on the C: drive, the share name is SMS_PKGC). When SMS is placing a Package for Workstations onto a distribution server, it attempts to place the package on the drive that contains the SMS_PKGx share. If the share doesn't exist, it will attempt to create the share on the drive that contains the SMS directory and files. If the drive does not have enough free disk space, SMS will attempt to create a new SMS_PKGx share on the NTFS drive with the most free disk space. As a last resort, SMS will create the share on a FAT partition.

You can influence which partition SMS distributes packages to by creating a new SMS_PKGx share on a distribution server. For instance, if your server has a SMS_PKGC share on the C partition, and you add a new drive as the D partition, you can create a new share called SMS_PKGD pointing to the D partition.

If there is more free disk space on the new partition, SMS will use it for package distributions to the server.


Packages for Sharing

SMS does not create a single share for all Packages for Sharing. When you create a Package for Sharing, you specify the share name to be used on the distribution server (this is specified in the Setup Package for Sharing dialog box).

You can influence the drive SMS uses to store the package by creating the share prior to starting the job that distributes the package. For instance, to share a package called Appo on the D drive of a particular distribution server, you can:

Create the Package for Sharing, specifying the share name as AppoShare.

Create the AppoShare share on the D drive of the server.

Create the job to share the Appo package to the distribution server.

When SMS places the package onto the distribution server, it will place the package into the existing AppoShare share (instead of creating a new share).


Interpreting SNMP Traps

You can convert Windows NT events to SNMP traps, as described under "Debugging SNMP Traps" in the Systems Management Server Resource Guide from the first BackOffice Resource Kit. These SNMP traps can be sent to third-party network management stations, as well as to your SMS server. Since third-party software may not be able to interpret the data, however, you will need to know what information is included in the SNMP trap, and how it is organized, so that you can use the information once it arrives.

This section explains the components of the SNMP traps created by the Event to Trap Translator. It also explains why you may choose to use the trap-trimming feature, and how to implement trap trimming.


Components of Traps Generated from Windows NT Events

Each SNMP trap created from a Windows NT event includes at least the following nine components.

  • Object Identifier
  • Network Address
  • Generic trap ID
  • Specific trap ID
  • Timestamp
  • Message
  • UserName
  • ComputerName
  • EventType
  • EventCategory

The last five of these components comprise the variable bindings (VarBind) list. If any insertion strings are included in the message, they are added as additional VarBinds.

Object Identifier (Object ID)

The Object ID is used in all SNMP traps sent by the Event to Trap Translator. It contains three parts. The first two parts are Microsoft's Enterprise Object ID (1.3.6.1.4.1.311) and a sequence indicating that the traps are sent by the Event to Trap translator (1.4.1). So each Object ID sent by the Event to Trap Translator begins with the sequence

1.3.6.1.4.1.311.1.4.1

The remainder of the Object ID is generated from the Event Source as it appears in the Event Viewer—for example "SMS" or "MSSQLServer". The characters from the Event Source string are converted to ASCII values ("SMS" becomes 83 77 83), and this value is preceded by the length of the string (3 in this instance). So, for the string "SMS", the variable portion of the Object ID is 3.83.77.83 and the final Object ID is

1.3.6.1.4.1.311.1.4.1.3.83.77.83

Network Address

The IP address of the computer generating the trap.

Generic trap ID

For translated Windows NT events, this is always 6, indicating an enterprise-specific trap.

Specific trap ID

This is the 32-bit Event ID of the Windows NT Event.

Bits 31 and 32 of the 32-bit event ID are the default severity of the error, normally displayed either as an icon representation in the Windows NT Event Log, or as the Type entry when viewing an event in detail. They can be interpreted as follows:

00 | Success
01 | Informational
10 | Warning
11 | Error

In the Event Viewer, you only see the lower 16 bits of the event ID; the first 16 bits of the specific trap ID are actually the Windows NT event ID displayed within the Windows NT Event Log. To interpret the first 16 bits, you must convert them from hexadecimal to decimal: this gives you the Event ID number. You can then use this to look up the event for that Event ID.

You can use ERROR32.EXE, included with this Resource Kit, to display the text of an error message for a specified Windows NT (Win32 subsystem, driver, or service) error code.

Timestamp

The time (in hundredths of a second) since the SNMP agent was started.

Message

The message component is provided by calling the Win32 API FormatMessage() for the data from the Event Record. It is of SNMP type DisplayString. The message component lists the string associated with the event, with the string substitutions supplied. Any formatting characters, such as new lines and tabs, are also converted.

Each insertion string will be included as a separate VarBind. These insertion string VarBinds appear at the end of the trap.

UserName

This is the user name of the account from which the event was generated. It is equivalent to the User field in the Event Viewer, and is of SNMP type DisplayString.

ComputerName

This is the name of the computer from which the event was generated. It is equivalent to the Computer field in the Event Viewer, and is of SNMP type DisplayString.

EventType

This is the classification type of the event by the NT operating system (for example, "Information," "Error," "Warning"). It is equivalent to the Type field in the Event Viewer, and is of SNMP type DisplayString.

EventCategory

This is the classification of the event, as defined by the source. It is equivalent to the Category field in the Event Viewer, and is of SNMP type DisplayString.


Trap Trimming

Traps longer than 4 K may be too large for some routers or other network devices to forward successfully, in which case they are dropped. This maximum length can easily be exceeded if the message string for an event is very long. However, the Event to Trap Translator includes a feature that enables you to specify a maximum trap length, and to specify what portions of the message should be trimmed first to reduce a longer trap to the length you have specified. This feature is available through the Settings button in the Event to Trap Translator.

If a trap is longer than the maximum you have specified, it is trimmed by one or more entire strings. You can set the Event to Trap Translator to trim either the formatted message or the insertion strings first. For example, if Trim Insertion Strings First is set, and the trap is too long, then the last insertion string is reduced to a zero-length string in the VarBind. If the trap is still too long, then the next is reduced to zero length, and so on. The VarBinds themselves are not deleted. There will always be the correct number of VarBinds, but some of them may contain zero-length octet strings.

Deciding Which Strings to Trim First

The message strings for the events are stored in message DLLs; each event source has its own message DLL. The names of the DLLs are stored in the Registry on the computer that sends the traps. If the application that receives the traps has access to the DLL containing the message strings (the same DLL used to generate them), then you do not need the Message VarBind. The receiving application can either read the registry and open the message DLL remotely, or generate its own mapping of event sources to local copies of the message DLLs. In this case, choose Trim Formatted Message First.

Also choose Trim Formatted Message First if the specific information in the insertion strings is what is most important to the receiving application.

If the Message DLL is not available and it is this basic message that is most important, choose Trim Insertion Strings First. Although the specific information provided by the insertion strings may be lost, the basic message should be intact.


SMS Registry Reference

Windows systems store their configuration information in a database called the registry. In early versions of Windows (Windows 3.x and Windows for Workgroups), the registry was a simple database containing only application-related data. However, in Windows 95 and Windows NT, the registry contains configuration information for the entire computer—hardware, software, device drivers, network protocols and adapters, and the operating system itself. The registry provides a secure, unified database that stores all of this configuration information in a hierarchical form. For more information about the registry, see the Microsoft Windows NT Workstation Resource Kit: Windows NT Workstation Resource Guide.

Caution The registry stores information that is critical to the correct operation of the computer. Editing data directly in the registry can cause severe errors in loading hardware and software, and may prevent you from being able to use the computer. Whenever possible, use the administrative tools such as Control Panel and Service Manager to make configuration changes on the computer, rather than changing data directly in the registry.


The Registry Editor

The registry is organized in a tree format that can be viewed and modified with a utility called the Registry Editor (REGEDT32.EXE in Windows NT, REGEDIT.EXE in Windows 95). The Registry Editor displays windows, each of which represents a predefined key on a local or a remote computer. Each window contains a split-pane tree view. The left-hand pane of the tree view displays folders that represent the registry keys. The right-hand pane displays the values associated with the selected key.

Within the Registry Editor, you can assign value entries to new keys or you can alter the value entries assigned to a currently selected key. Value entries in the registry appear as a string that consists of three components in the following order: the value name, the data type, and the value itself. There are five data types defined and used by the system:

  • The REG_BINARY prefix identifies a value entry as binary.
  • The REG_SZ prefix identifies a value entry as a data string.
  • The REG_DWORD prefix identifies a value entry as a 4 byte (DWORD) entry.
  • The REG_MULTI_SZ prefix identifies a value entry as a multiple string.
  • The REG_EXPAND_SZ prefix indicates that a value entry is an expandable string.

An example of a value entry of type REG_DWORD follows:

RegistrySizeLimit : REG_DWORD : 0x800000

Each value class has an editor that bears the same name as the class. To use the editor that corresponds to these classes, either double-click the value entry or click the corresponding command on the Edit menu.


The Windows NT Predefined Registry Keys

Five keys are predefined in the Windows NT version 4.0 registry: HKEY_CURRENT_USER, HKEY_USERS, HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, and HKEY_CURRENT_CONFIG. When accessing the registry of a remote computer, only two predefined keys, HKEY_USERS and HKEY_LOCAL_MACHINE, appear.

A description of each of the predefined registry keys follows:

HKEY_CURRENT_USER

This key is the root of the user profile for the user who is currently logged on. The user profile contains information that defines the behavior and appearance of the user's desktop, network connections, and other environment settings. HKEY_CURRENT_USER is a subkey of HKEY_USERS.

HKEY_USERS

This key is the root of all user profiles on the computer. It includes HKEY_CURRENT_USER and the default profile.

HKEY_LOCAL_MACHINE

This key contains configuration information about the local computer system, including hardware and operating system data.

HKEY_CLASSES_ROOT

This key contains information that is used to open the correct application when a file is opened indirectly (for instance using file association in the Windows NT Explorer or with Object Linking & Embedding). This key provides compatibility with the Windows 3.1 registration database. HKEY_CLASSES_ROOT is an alias of HKEY_LOCAL_MACHINE\Software\Classes.

HKEY_CURRENT_CONFIG

This key contains information about the current hardware profile of the local computer system. Hardware profiles are sets of changes to the standard configuration of services and devices established by data in the Software and System keys under HKEY_LOCAL_MACHINE. Only the changes appear in this key. HKEY_CURRENT_CONFIG is an alias of HKEY_LOCAL_MACHINE\System\CurrentControlSet\Hardware Profiles\Current. This key was introduced in Windows 95 and Windows NT version 4.0.


The SMS Registry

The following tables show the main registry keys used by SMS:

Note This document does not include all keys and values created by or used by SMS.

SMS may use registry keys created by the operating system or other applications. SMS may also create new keys or add values to existing keys created by the operating system or other applications.

In addition, if Program Group Control is being used, SMS will modify the registry as needed to run the application.

In HKEY_CLASSES_ROOT:

Primary key | Immediate subkeys | On Computer Types | Description
\SMS\ | Applications, Groups, PGC_Version, SMS_INI, Tasklist. | Windows-based computers running as SMS clients. | Information about the SMS client setup and software.

In HKEY_LOCAL_MACHINE\Software:

Primary key | Immediate subkeys | On Computer Types | Description
\Microsoft\SMS\ | Applications, Client Services, Components, Compression, Identification, Setup, Sites, SQL Server, and Tracing. | Applications and Client Services are present only on SMS clients; Identification and Tracing are present on both SMS clients and servers; all other keys are present only on SMS servers. | Information about the SMS system and its components.
\Microsoft \SNMP_EVENTS\ | EventLog. | Windows NT computers running as SMS clients. | Information about the Event to Trap Translator.

In HKEY_LOCAL_MACHINE\System\CurrentControlSet\:

Primary key | Immediate subkeys | On Computer Types | Description
\Services\ | SMS_Hierarchy_ Manager, SMS_Executive, SMS_Site_Config_ Manager, SMS_Inventory_ Agent_NT, SMS_Package_ Command_Manager_NT, SMS_Client_Config_ Manager. | SMS servers. | Information about the SMS Services.
\Services\BH\ | Enum, Linkage, Parameters, Performance, Security. | Computers running Network Monitor. | Information about Network Monitor.
\Services\NMAgent\ | Linkage, Parameters, Performance, Security. | Computers running the Network Monitor Agent. | Information about the Network Monitor Agent.
\Services\SNMP\ | Parameters. | Computers running the Windows NT SNMP service. | Configuration information supplied to the Windows NT SNMP service. The main keys are created by Windows NT, but SMS modifies some values.

In HKEY_CURRENT_USER\SOFTWARE\MICROSOFT:

Primary key | Immediate subkeys | On Computer Types | Description
\SMS\ | Applications, Login, MachineProperties, Main, MDIs, Preferences, SecurityAdmin, Sender Manager, Tables, ToolBar. | Windows NT computers running the SMS Administrator. | Information about the current user settings in the SMS Administrator.
\Network Monitor\ | Configuration. | Computers running Network Monitor. | Network Monitor configuration information.
\Windows NT \CurrentVersion \Windows\ | None. | Windows NT computers running as SMS clients. | This is a Windows NT key, but SMS modifies the LOAD value in this key and uses it to start the SMS client software at logon time.


Chapter 3 - Troubleshooting Remote Control

The remote control feature in SMS is used to directly monitor and control the computers in the SMS inventory database. Many problems using the remote control features of SMS are related to difficulties locating the client computer, difficulties with the remote viewing session itself, or both. The greatest number of potential problems involve failure to locate the client, and fall into three categories:

  • Inventory problems related to remote control
  • Client Remote Control Agent configuration problems
  • Network problems

The relatively few problems involving the remote viewing session itself fall into two categories: display problems and problems with passing keystroke information.

This chapter discusses known solutions to specific problems.

Note Many potential problems can be avoided by using the latest Service Pack for SMS.


Knowledge Base Articles

Where appropriate, these troubleshooting tips refer you to articles in the Microsoft Knowledge Base. The Knowledge Base is available free of charge at http://www.microsoft.com/kb. To view a specific article referenced in these pages, select Systems Management Server in the Choose product or technology drop-down list, and enter the article number in the Enter your search phrase text box. For example, the following screen would be used to view Microsoft Knowledge Base article Q126642.


Troubleshooting Difficulties Locating the Client

To successfully locate a client computer, three conditions must be met:

  • The computer must be inventoried correctly.
  • The computer's Remote Control Agent must be "listening" for this session.
  • The intervening network must be able to establish and maintain the session.
  • The proper options must be selected in the Help Desk Options section in the SMS client group on the client, and the Remote Control Agent must be loaded (minimized on the screen) at the client computer. These are not configured by default.

Troubleshooting Inventory Problems Related to Remote Control

Remote control is initiated in the SMS Administrator by double-clicking the Help Desk icon in the properties of an inventoried computer. The SMS Administrator uses SIGHTNT.DLL to attempt to initiate a session with the Remote Control Agent of the client by querying for the computer name (client name, IP address, or IPX address) and the address type (NetBIOS name, IP address, or IPX address) recorded in the inventory in the SQL database. In SMS 1.2, Service Pack 2, SIGHTNT.DLL also queries by the host name, in case the IP address listed in the database is out of syncwith the WINS database. The inventory information regarding the computer's network information and SMSID must correctly match an SMS client computer whose Remote Control Agent is currently "listening" on the network.

SIGHTNT.DLL looks in the SMS database to find the computer name and address. If the computer is not listed in the inventory, it will not be located and, therefore, cannot be remotely controlled.

Common inventory problems include:

  • The client has not been inventoried at all.
  • The client shares a computer name or address with another computer, and has an invalid SMSID (duplicate computer name or address)
  • The client shares an SMSID with another client (duplicate SMSID).
  • The client is running the Windows® for Workgroups operating system version 3.11, and has been inventoried with a computer name in lowercase letters.
  • The client's network address has not been correctly inventoried.

These problems are discussed in the following sections.

The Client Has Not Been Inventoried

Symptom:

The client computer name does not appear in the inventory. It may or may not have the SMS client files installed.

Troubleshooting:
  • Install the SMS client files on the computer by invoking SMSLS.BAT or RUNSMS.BAT.
  • If the client has the SMS client files on it, but does not appear in inventory, remove and reinstall the client.
  • Follow the steps listed in Microsoft Knowledge Base article Q126642, "Troubleshooting SMS Inventory Collection Problems," to track down any further problems.

Client Is a Duplicate with an Old, Invalid SMSID

Symptoms:
  • The same computer name appears next to different SMSIDs in the Sites window.
  • The message "Unable to Locate clientname" appears after "Trying Additional Protocols" (this message can indicate other problems, as well).
Troubleshooting:
  • Select the most recent occurrence of the computer name and see if SMS can locate it. If so, delete the older occurrence of the computer name. If SMS cannot locate the most recent occurrence of the computer name, you have additional problems. However, you should still remove or merge your duplicate inventory, using DBCLEAN.
  • If the problem persists, check to see why the SMS.INI file is being deleted, or why it is being locked during the verification process.

    Note Some MSTest scripts invoke INVDOS.EXE after installing a program to check to see if the program was installed correctly. If the SMS.INI file is locked, SMS Server cannot read it, and will respond as though the SMS.INI file did not exist at all – by reinstalling the SMS client. When the client is reinstalled, a new SMSID is assigned.

Client Shares an SMSID with Another Client

Symptoms:
  • The Help Desk icon and other icons may be missing in the affected client computer's properties.
  • The network is functioning correctly; other clients on the same subnet can be remotely controlled.
Troubleshooting:
  • If two computers share the same SMSID, delete the SMS.INI file on one of them. SMS will then create a new SMS.INI file, with a new SMSID.
  • Check to see if the clients have been "cloned"—preloaded with the SMS client files. If so, all these clones will have the same SMSID assigned. Delete the SMS.INI file from all the clones. SMS will then create a new SMS.INI file with a new SMSID.
  • Check to see if the .UID files on two logon servers overlap, or whether there are multiple .UID files on a logon server. Synchronize the site server with the *.UID files on the logon servers, as described under "Restoring a Primary Site" in Chapter 15, "System Maintenance," of the Administrator's Guide for SMS 1.2. If there are multiple .UID files, find the incorrect .UID file and rename or move it. See Microsoft Knowledge Base article Q127052. "SMS Unique ID (SMSID) Allocation," for information on how UIDs are assigned.

Windows for Workgroups 3.11–based Clients Inventoried with a Computer Name in Lowercase Letters

Symptoms:
  • The computer name of a Windows for Workgroups 3.11 client appears in lowercase letters, often the result of manually configuring the SYSTEM.INI file on the client.
  • The message "Unable To Locate Clientname" appears after "Trying Additional Protocols." (This error message can indicate other problems, as well.)
Troubleshooting:

This problem appears if you are using a version of SMS earlier than 1.2; usually when you use custom batch processes to assign names to Windows for Workgroups–based computers. Windows versions 3.11 and later automatically convert the computer name to uppercase when writing to the SYSTEM.INI file.

The best solution is to upgrade to SMS 1.2. See Microsoft Knowledge Base article Q149495, "Remote Control Fails with Lower Case Computer Name," for a work-around for sites using earlier versions of SMS.

The Client's Network Address Has Not Been Correctly Inventoried

Symptoms:
  • The TCP/IP or IPX address of the client is either wrong or missing in the Network section of the Personal Computer Properties window.
  • The message "Unable To Locate Clientname" appears after "Trying Additional Protocols." (This error message can indicate other problems, as well.)
Troubleshooting:
  • Upgrade to Service Pack 2 for SMS 1.2.
  • If no address appears, check to see if the computer has a dial-up adapter, and if the dial-up adapter is first in the bindings for the protocol in question. If the dial-up adapter is first, SMS returns the address of the dial-up adapter (which should be 0.0.0.0).

    For Windows NT–based clients, click Network in the Control Panel and then click Bindings to move the binding for the network adapter to the first position.

    For Windows 95-based clients, click Network in the Control Panel and choose the adapter for which you want to change the bindings. Then choose the Bindings tab to set the bindings.

  • If the wrong IP address appears, check for reasons that the IP address might have changed. If you are using DHCP, the lease times for IP addresses must be longer than the inventory period. If the lease time is too short, the IP address in the inventory may be out of date. Reinventory the client to get current address information. To avoid this problem, make sure the DHCP lease time is considerably longer than the inventory interval (ideally by lengthening the lease time rather than shortening the inventory interval). A similar situation occurs if the WINS database has not been replicated; this problem is fixed in SMS 1.2 Service Pack 2.
  • If you are attempting to use remote control using SMS 1.2, TCP/IP sockets, and Windows for Workgroups 3.11, see Microsoft Knowledge Base article Q156372, "TCP/IP Inventory Is Not Collected on SMS 1.2 WFW 3.11 Clients." This problem is fixed in SMS 1.2, Service Pack 1.
  • If the client computer has two network adapter cards that are using different subnets, and you are not using Service Pack 2 with SMS 1.2, SMS inventories only one IP address for use with remote control. If WUSER or WUSER32 is monitoring the other IP address, it will not respond and remote control cannot find the computer.

Troubleshooting Client Remote Control Agent Configuration Problems

Improper or unsupported client configurations are perhaps the most frequent cause of the "Unable to locate" message. The server side (SIGHTNT.DLL on the SMS site server) calls the client side (WUSER.EXE for 16-bit clients or WUSER32.EXE for Windows NT or Windows 95). If anything interferes with WUSER.EXE loading properly, the client will not be "listening" for SIGHTNT.DLL's call. This can happen if the Remote Control Agent is not loaded, or if a third-party TSR is preventing the call from being received. If SIGHTNT.DLL's call is accepted by another component (such as a third-party protocol stack) before WUSER.EXE or WUSER32.EXE can respond to it, the client cannot respond.

Common client configuration issues include:

  • Other TSRs conflicting with THE supporting TSRs for WUSER.EXE or WUSER32.EXE (USERTSR.EXE or USERIPX.EXE)

    Note Neither USERTSR.EXE or USERIPX.EXE is used with SMS 1.2 clients running Windows.

  • Failure to configure remote viewer options or load the Remote Control Agent/service
  • Hardware problems

Other TSRs Conflicting with WUSER.EXE's Supporting TSRs

Symptoms:
  • The Help Desk Options and/or Remote Control Agent icons may be missing from the SMS program group on the client.
  • The client may experience a general protection fault during remote control.
Troubleshooting:
  • Remove all TSRs (such as virus scanners and virtual memory managers) from the AUTOEXEC.BAT file and the load line of the WIN.INI file, and reinstall the SMS client software.
  • If the client can now be successfully remotely controlled, add each TSR back in, one at a time, until the conflict reoccurs. Query the Knowledge Base on "Remote Control," "SMS," and the name of the TSR in question for any possible workarounds. If a virus scanner is in conflict, consider using a daily SMS job to scan for viruses.
  • The SMS client for Windows 95 causes a general protection fault in Microsoft Office when you attempt to establish a remote control session without the shortcut bar and then enable the shortcut bar. Should you experience this problem, upgrade to SMS 1.2, or call technical support for the fix.

Failure to Configure Remote Viewer Options or Load the Remote Control Agent/Service

Symptoms:
  • WUSER.EXE (for 16-bit clients) or WUSER32.EXE (for Windows NT or Windows 95) does not appear minimized on the Windows–based client workstation.
  • The remote control service does not load on Windows NT–based clients.
Troubleshooting:
  • Make sure the Remote Troubleshooting check box is selected (checked) in the Clients dialog box for the site properties.
  • Make sure the Allow Remote Control option is selected in the Help Desk Options in the SMS Client program group on the client computer. This can be verified remotely by looking in the client's SMS.INI file for the entry Allow Remote Takeover=yes.
  • Make sure the Remote Control Agent has been loaded on the client computer. The Remote Control Agent icon will be minimized. You can verify that the Remote Control Agent is loaded by typing mem /c at the command prompt on the client computer, and looking for USERTSR (if using NetBEUI, NWLINK, or IP), or USERIPX (if using NetWare's IPX clients). (These TSRs are not required for clients based on Windows 95, Windows NT, or Windows for Workgroups, but they are required for clients based on other Windows-based clients.)
  • SMS 1.2 provides the added functionality of remote control as a service for the Windows NT operating system. Usually the only additional problem that may surface is that the SMS service account, under whose context the remote control service is installed, does not have "administrator" rights, nor does it have "log on as a service" rights for the workstation. If this is the case, the SMS client files will be installed, but neither the inventory agent service nor the remote control service will start. (To see if the remote control service is started, click Services in the Control Panel, or type net start at the command prompt of the Windows NT–based client). This lack of rights will show up in the CLICFG.LOG file on the SMS site server. Make sure the domain administrators are part of the local administrators group on the client, and that the SMS service account is a member of the domain admins group. Verify that the service account has "log on as a service" rights.

Hardware Problems

Sometimes a bad network adapter or other hardware problems can cause remote control to fail. If everything else checks out, try swapping out the network adapter, or try an identical hardware configuration with a fresh installation of the network operating system. If you can isolate the problem to a particular piece of hardware, try querying the Knowledge Base on "Remote Control," "SMS," and the name of the offending hardware.

Troubleshooting Network Problems

SMS allows remote control over a variety of networking configurations using Microsoft's NetBIOS-capable protocols (NetBEUI, Microsoft TCP/IP-32, and NWLINK), and using sockets with NetWare's IPX (NETX and VLM) protocols. SMS 1.2 supports remote control using IP sockets for the Windows operating systems.

For SMS 1.2, in the Client section of the Site Properties dialog box, the Options section contains three choices: NetBIOS LANA, Windows Sockets over TCP/IP, or IPX. These options are not just for Windows NT. They take effect for all of the Windows operating system family. Selecting one of these options causes the corresponding entry to be written to all the SMS.INI files on your site: NetBIOS, IP (for sockets), or IPX.

Note For NetWare clients, if you select Windows Sockets over TCP/IP and the remote protocol specified in the SMS.INI file is not present on the client, SMS tries to bind to the next available protocol on the client. Thus it finds NetWare's IPX, and binds to it automatically.

In order for the remote control session to be established, the network must be functioning properly. As appropriate, protocols must be initialized, and name resolution, packet sequencing, session establishment, messaging, routing, and bandwidth availability must all be working properly.

Common network-related problems include the following:

  • Unsupported or corrupted network client
  • Protocol configuration or binding order problems
  • Wrong LANA number configured
  • NetBIOS name resolution problems
  • Insufficient routing configurations
  • Insufficient bandwidth
  • Insufficient NetHeapSize on the client

There are also special considerations for remote control over RAS. These issues are discussed in the following sections.

The Network Client Is Unsupported/Corrupted

Symptoms:
  • The message "Unable to locate clientname" appears after "Trying Additional Protocols." (This message can indicate other problems, as well.)
  • The message "Unable to initialize...." may appear on the client when the computer is restarted.
Troubleshooting:
  • Check your network client against the list of supported clients in the SMS documentation and release notes.
  • If the client's network operating system is unsupported, upgrade to a supported client. This includes upgrading to the latest Windows for Workgroups redirector, and the Microsoft TCP/IP-32 stack (both found on your Windows NT Server CD-ROM).
  • If you have any third-party network client software or protocol stacks, remove them. Then add them back in, one at a time, until the offending stack is identified. If you must run the third-party stack, try a different load order, or try using a different protocol for remote control (for example, Windows Sockets over TCP/IP with SMS 1.2).
  • Occasionally, a network client can become corrupted, particularly when using specially configured "images" or "clones" that are stored on the network for administrative installations. Try a fresh installation from the manufacturer's original source media.

Protocol Configuration or Binding Order Problems

Symptoms:
  • The message "Unable to locate clientname" appears after "Trying Additional Protocols." (This message can indicate other problems, as well.)
  • The message "Unable to initialize protocol" may appear during the boot process on the client.
  • The message "NetBIOS is not loaded on this workstation...." may appear during the boot process on the client.
Troubleshooting:
  • The message "Unable to initialize...." on client boot can occur if unsupported protocol stacks are present. In this case, completely remove the unsupported protocols from the client (don't just remark them in the AUTOEXEC.BAT file). You can verify which protocol is in use by selecting the Remote Control Agent icon while it is minimized. You can also check the Default Protocol in the [Sight] section of the SMS.INI file.
  • If you receive the message "NetBIOS is not loaded...," verify that the SMS client has been installed properly. In particular, check to see which operating system SMS detects for the client. You can check this by looking at the OS entry in the [SMS] section of the SMS.INI file. (1=MS-DOS, 2=16-bit Windows, 3=OS/2, 4=Windows NT, 5=Windows 95.)

    If the operating system on the client is Windows, but SMS has an OS entry indicating that it is an MS-DOS–based client, the Windows directory may be too far down in the path in your AUTOEXEC.BAT file. (This problem only occurs when running versions of SMS earlier than 1.2.) Move the Windows directory to the beginning of the path, and reinstall the SMS client. See Microsoft Knowledge Base article Q138829, "SMS Incorrectly Identifies Windows Clients as MS-DOS Clients," for more information on this problem.

  • Problems with IPX and NWLINK
    • If Windows for Workgroups is configured to use both the NetWare shell and the NWLINK protocol, NWLINK grabs the IPX packets, but does not pass them on to WUSER.EXE or WUSER32.EXE. The solution is to remove NWLINK from the client. For more information, see Microsoft Knowledge Base article Q128145, "Cannot Remote Control Windows IPX/NetBIOS Client."
    • If a Windows 95–based client receives the message "IPX is not loaded for this workstation. Would you like to load the drivers for Win95?" use the cliopts utility to configure USERIPX as described in Chapter 10, "Remote Troubleshooting," of the SMS 1.2 Administrator's Guide.
    • If you receive the message "Unable to initialize IPX protocol" on a client running Windows 95, see Microsoft Knowledge Base article Q154411, "SMS Err Msg: Unable to Initialize IPX Protocol." For Windows clients, be sure to remove any unsupported protocol stacks completely; don't just remark them.
  • Problems with NetBIOS over TCP/IP
    • Remote control is not supported on any third-party TCP/IP stack. Always update clients running Windows for Workgroups or Windows 95 to the latest redirector and Microsoft TCP/IP-32 (found on the Windows NT Server CD-ROM).
    • Typing nbtstat -n in a command window is a quick way to verify that the TCP/IP stack is properly bound and that the Remote Control Agent is running. If everything is working properly, nbtstat -n should return a <43> extension next to the computer name. If the <43> service does not show up, and no TSRs are conflicting, check for a dial-up adapter configured for TCP/IP, and remove the binding for TCP/IP to the adapter.

Wrong LANA Number Configured

NetBIOS is an interface between an application and a protocol. It consists of a set of function calls. NetBIOS network applications such as the SMS remote control program set up logical network sessions between two computers by riding on top of a transport protocol that supports NetBIOS (NetBEUI, TCP/IP, NWLink). Each NetBIOS-capable protocol binding can support one NetBIOS session at a time. If five pairs of NetBIOS network applications were communicating at a time, each would establish its own logical network session. Each computer running the network applications would need five distinct bindings of any protocols that support NetBIOS.

In order for a network application to know on which logical network session to send and receive its function calls, each is assigned a LAN Adapter number (LANA number). The two network applications sharing a NetBIOS logical network session must be configured to send and receive on the same LANA number. If they are not configured to the same LANA number, you will get the "Trying additional protocols" message. Each binding is then tried in turn, and when the proper binding is tried, the client will be located. Setting LANA numbers is usually necessary only to speed up the location process.

Symptom:

The "Trying Additional Protocols" message appears. The client will probably be located, but you should avoid this message and delay.

Troubleshooting:

The following is an example of how to set the LANA number for both the client and the server using NetBIOS over TCP/IP.

Double-click the server's NetBIOS interface by activating the Network icon in the Control Panel, and set NetBT to LANA 0. (If another protocol is on LANA 0, set it to the LANA number NetBT had.)

For Windows for Workgroups–based clients, check the [NBT] section in SYSTEM.INI, and make sure LANABASE=0.

For Windows 95–based clients, set TCP/IP as the default protocol.

For MS-DOS 3.0–based clients, check the [NETWORK.SETUP] section in PROTOCOL.INI, and make sure LANABASE=0.

For LAN Manager 2.2c–based clients, check the [TCPIP_XIF] section in PROTOCOL.INI, and make sure LANABASE=0.

See the "Remote Troubleshooting" Chapter of the SMS Administrator's Guide for more information on configuring the LANA number.

NetBIOS Name Resolution Problems

The NetBIOS application program interface permits the use of computer names, rather than alphanumeric computer addresses, to identify computers on a network. TCP/IP internetworks require a name resolution service to convert computer names to IP addresses and IP addresses to computer names. If the name resolution is not working properly, remote control may be unable to function.

Symptoms:
  • Remote control works locally, but not across a router.
  • Remote control may work only for those computers that share a primary WINS server with the computer running SMSAdmin.
  • You can ping the IP address, but not the NetBIOS name.
  • A captured Network Monitor trace shows that the "CLIENTNAME C" name query is failing.
Troubleshooting:
  • Name resolution and routers
    • Verify that UDP Ports 137 and 139 are enabled by trying a net use from the server to the client, or to other clients on the same segment.
    • Verify that UDP Port 138 is enabled by trying a net send from the server to the client, or to other clients on the same segment.
    • For NWLINK networks, verify that the router is configured to pass type 20 packets for NWLINK NetBIOS support. If not, reconfigure the router to pass these packets.
  • Name resolution and WINS

    From a command window at a server, type nbtstat -a clientname, then look for the clientname <43> entry, which is the WINS registration of the remote control agent's extension.

    If no <43> service registration appears at the server, type nbtstat -n on the client itself and check for the <43> service.

    If the <43> service is present on the client, but cannot be seen from the server when you type nbtstat -a clientname, either look for problems with WINS or make sure that UDP Ports 137, 138, and 139 are not disabled on your routers. Check all relevant WINS databases for the <43> service by clientname. This is especially pertinent if WINS database replication is configured. See Microsoft Knowledge Base article Q155744, "SMS: WINS Replication Causes Remote Control Delay," for more information. This problem has been fixed in SMS 1.2, Service Pack 2.

    If the <43> service is not present on the client, there is a configuration problem on the client. Check for a modem on the client and, if present, disable the NBT binding on the modem.

    Try reinstalling TCP/IP. For Windows for Workgroups–based clients, use the updated redirector and the Microsoft TCP/IP-32 3.11b stack. Check also for third-party TSRs and protocol stacks and, if found, remove them and try again.

    If the computer running SMS Admin and the client computer have different primary WINS servers, make sure WINS replication is not the cause of the problem. Check for the clientname <43> entry in both WINS databases. See Microsoft Knowledge Base article Q155744, "SMS: WINS Replication Causes Remote Control Delay," for more information.

  • Name resolution and LMHOSTS

    Verify that the LMHOSTS file is configured properly. For information on configuring the LMHOSTS file see "Configuring Remote Support Across a Router" in Chapter 10, "Remote Troubleshooting," of the SMS 1.2 Administrator's Guide.

    Note Only the server's LMHOSTS file needs to be configured with the remote extensions.

    Verify that the IP address is correct.

    Verify that the computer name is spelled correctly, and that C is in the 16th position.

    Verify that there are no multiple entries for "CLIENTNAME C."

    If another copy of the LMHOSTS file is on another working server, rename the local copy, and copy the file to the server that is not working. Type nbstat -R to reload the cache.

    Try creating a new LMHOSTS file, and type nbtstat -R to reload the cache.

    Make sure there is a blank line on the last entry of the LMHOSTS file.

Insufficient Routing Configurations

For all networking configurations, routers must be functioning properly to support remote control. If your routers are dropping packets or corrupting the data portion of the packets, you may see symptoms like dropped sessions or general protection faults on the clients during a remote-control session. Limit remote control sessions to three hops. Because remote control occurs in real time, too many hops can seriously impair performance.

For remote control to function properly, certain ports must be enabled on the routers.

Note Enabling a port on a router is not necessarily the same thing as bridging a protocol. For example, for NetBIOS over TCP/IP name resolution to work, routers must have UDP Port 137 enabled. Thus any packet specifically sent to this port will be forwarded. Only name queries, such as requests for name resolution to WINS servers, are sent to this port. NetBEUI is not being bridged.

To use NetBIOS over TCP/IP, UDP Ports 137, 138, and 139 must be enabled. Port 137 is for name resolution, Port 138 is for messaging (sending the screen image), and Port 139 is for sessions.

To use NetBIOS over NWLINK, Type 20 packets must be forwarded. Type 20 packets are the packets that provide NetBIOS support, and forwarding these can cause more traffic than is desired in some environments.

For TCP/IP sockets and IPX, no special configuration is required.

Symptom:

Clients can be located on the local segment, but not across the router.

Troubleshooting:
  • Verify that UDP Ports 137 and 139 are enabled: Enable only the TCP/IP bindings to the network card and then try a net use from the server to the client, or to other clients on the remote segment.
  • Verify that UDP Port 138 is enabled: Make sure that Winpopup is enabled on the client, and that only TCP/IP bindings are enabled. Then try a net send from the server to the client, or to other clients on the same segment.
  • Check the number of hops on a TCP/IP network by using the TRACERT command. (TRACERT is installed when the TCP/IP protocol is installed on the client computer.)
  • Verify that Type 20 packets are being forwarded: With only the NWLINK protocol bindings enabled, try a net use to a computer across the router.
  • In some cases, if the computer from which SMS Admin is being run is not on the same ring as the SMS Server, remote control does not work. See Microsoft Knowledge Base article Q142045, "Remote Control Fails Over IPX Token-Ring Wide Area Network," for more information.
  • Troubleshooting dropped packets or corrupted data is beyond the scope of this Guide. Call Microsoft Product Support for technical support.

Insufficient Bandwidth

A minimum transfer rate of 14,400 bits per second is recommended for remote control.

Symptoms:
  • Completely inadequate bandwidth will return "Unable to locate computername" during times of peak usage, but will locate the client successfully during low usage.
  • If bandwidth is marginally adequate, the remote control session may start successfully, but the screen fails to draw correctly—producing no icons, very poor redraw of program groups, and other screen problems. All other remote troubleshooting utilities may work correctly.
Troubleshooting:

Perform a ping test from the Diagnostics utility in SMS (not the TCP/IP command-line ping test) on both a successful computer and an unsuccessful computer. If bandwidth is a consideration, you should see a significant difference. For a rough calculation of the bandwidth on TCP/IP networks, multiply Average Packets/Second by 72 (the UDP packet size) to get the bytes per second. This result must be greater than or equal to 14,400 to meet the recommended bandwidth.

Insufficient NetHeapSize on Client Causes Dropped Sessions

Symptoms:

Remote control may initialize, but the session terminates unexpectedly. (This is a very rare problem.)

Troubleshooting:

Session failures can occur because of network problems. Try setting the NetHeapSize value to a setting greater than 24 in the [386ENH] Section of the SYSTEM.INI file.

Special Considerations for Remote Control Over RAS

Symptoms:

The "Unable to locate computername" message only appears for RAS clients that seem to be otherwise configured correctly.

Troubleshooting:
  • SMS cannot access the remote client because the Remote Access Service is not configured to allow listens to be posted for all NetBIOS names. By default, RAS will only allow NCB.LISTENs to be posted for Server and Messenger service NetBIOS names. See Microsoft Knowledge Base article Q129603, "Using Systems Management Server Remote Control over a RAS Server," for more information.
  • If the computer is running Windows for Workgroups and uses both via RAS and local network connections, the problem may be that the computer was added to the inventory while logged on locally. In this case, the inventory uses the adapter information rather than the RAS adapter information. Because SMS uses the inventoried address to find the computer, it does not find the computer when it is logged on via RAS. This problem has been fixed in SMS 1.2 Service Pack 2.


Troubleshooting the Remote Viewing Session

Once the client has been located and permission granted, the remote viewing session begins. A variety of options and settings are available, and are documented in the "Remote Troubleshooting" chapter in the SMS Administrator's Guide. Unless you understand the consequences of altering these settings, they should be left at the defaults.

One issue that arises is the speed you can expect in remote viewing. Currently, only SMS includes encryption, so only SMS remote viewing is secure. Some people have stated that certain third-party products are faster than SMS remote viewing; this is an effect of the encryption phase.

For faster remote viewing in SMS, lower the resolution on the client computer and force16-color viewing. This decreases the amount of information that goes across the network.

Remote viewing is fastest over NetBEUI, and NetBIOS over TCP/IP is generally a bit faster than TCP/IP sockets.

For a successful remote viewing session:

  • The server must be able to use the display information sent from the client.
  • The client must be able to use the keystroke information sent from the server.

Troubleshooting Display Problems

Once the client computer's Remote Control Agent has been located and permissions have been granted, the Remote Control Agent hooks into the video driver graphic functions, encrypts them, and sends the information to the SMS Admin workstation.

For the display to appear properly, the SMS Admin workstation video driver and card must be able to interpret and display the information they receive, including all drawing functions, colors, and font information. The wide variety of display drivers and video cards available complicates this process.

Further, graphical information requires a great deal of memory. The higher the resolution, and the greater the detail in the display, the more memory required to store the information. When this information is sent over a network in "real time" to display on another computer, a considerable amount of bandwidth is used.

Common display problems include display incompleteness or color-mapping problems and font problems.

Display Incompleteness or Color-Mapping Problems

Symptoms:
  • The Quick Viewer Screen may be completely gray.
  • The Quick Viewer Screen may display different colors than the client.
  • The Quick Viewer Screen may be missing, or may contain incompletely drawn icons or program groups.
  • The display refresh speed may be very slow.
Troubleshooting:
  • Try forcing 16-color viewing: In the Quick Windows Viewer, from the Control menu, choose Configure. Then choose Force 16 Color Viewing (Faster Viewing).
  • Try decreasing the resolution on the client computer, especially if the client computer has greater resolution than the computer running SMS Admin. Or, increase the resolution on the computer running SMS Admin.
  • Try using the generic video drivers included with Windows.
  • Try swapping the client video card for one that works in another computer.
  • If you are using a Cirrus video adapter and driver, you may be encountering a known problem that occurs when a Cirrus video adapter and the Cirrus driver V1.24 (driver GD5434 set to more than 16 colors) are used together. This problem is described in Microsoft Knowledge Base article Q152105, "Quick Viewer Font Problem(s) When You Remote Control to Clients;" a hot fix is available. You might also query the Knowledge Base for your hardware, "SMS," and "Remote Control."
  • Check the available bandwidth. Low bandwidth can cause these kinds of problems.
  • Perform a ping test from the Diagnostics utility in SMS (not the TCP/IP command-line ping test) on both a successful computer and an unsuccessful computer. If bandwidth is a consideration, you should see a significant difference. For TCP/IP networks, multiply Average Packets/Second by 72 (the UDP packet size). This result must be greater than or equal to 14,400 to meet recommended minimums.
  • For clients running Windows NT 3.51, try toggling the "Install Accelerated Screen Transfer on Windows NT Clients" option.

Font Problems

Symptoms:

Fonts may be missing, may be an incorrect type, may be an incorrect size, or may be an incorrect split.

Troubleshooting:
  • Follow the same procedures as for troubleshooting display completeness or color-mapping problems.
  • If characters are preceded with a caret (^), you can correct this problem by pressing the ctrl key once.
  • See whether fonts are installed on the client that are not available to the computer running SMS Admin. SMS maps equivalent fonts, and sometimes the font does not map well. Either remove the custom fonts on the client computer, or add them to the computer running SMS Admin. For example, you might see the following custom font entry in the SYSTEM.INI [BOOT] section:

system.drv=atmsys.drv

Disable the custom fonts, and restore the default setting:

system.drv=system.drv

  • Consult the following Knowledge Base Articles:
    • Q134340: "Font Display Problems Using Systems Management Server Helpdesk" (Windows 95 with Plus! pack client TrueType fonts and glyphs corrupted)
    • Q137306: "Fonts Incorrectly Displayed During Windows 95 Remote Control" (if Plus! Pack is installed on client)
    • Q138239: "Characters Missing in Quick Window Viewer During Remote Control" (MS-DOS–based client only)
  • Upgrade to SMS 1.2 Service Pack 1. This is especially applicable for ATM fonts.

Troubleshooting Passing Keystroke Information Problems

Very few problems arise regarding passing keystrokes to the client computer. Basically, the keyboard drivers on the SMS Admin computer must be compatible with those on the client.

Symptoms:

Keystrokes on the SMS Admin computer do not have the expected effect on the client.

Troubleshooting:

  • If you are using SMS 1.0, hot keys used during remote control of a client from SMS Admin may not work on the client. This problem is corrected in versions of SMS later than 1.0. For more information, see Microsoft Knowledge Base article Q135124, "System Keys Not Passed Through to Client Using Remote Control."
  • If this problem occurs on all clients, try installing the SMS Admin Tools on another computer with a different make of keyboard. If this computer can successfully pass keystrokes, the problem may be the keyboard or keyboard driver at the original computer running SMS Admin. If this problem occurs on only a single computer, the problem may be the keyboard or a corrupted keyboard driver on the client. Try using a different keyboard on the server, or reinstall the keyboard driver on the client. If this problem occurs with only a certain make or model of keyboard, contact Microsoft Product Support.


Chapter 4 - Tools

Introduction

This chapter explains how to use, and in some cases install, the Microsoft® Systems Management Server tools provided in the Microsoft BackOffice™ Resource Kit.

This chapter is written for people who are already familiar with Microsoft Windows NT®. For general information about Windows NT, including keyboard equivalents to menu and mouse actions, see the Windows NT online help.

Disclaimers

Many of these tools were developed internally at Microsoft. Any use of any of these tools is at your own risk. These tools are provided "as is" without warranty of any kind. Microsoft disclaims any implied warranty of merchantability and/or fitness for a particular purpose.

These tools have not been localized: they are written and tested in English only. Using these tools with a different-language version of Windows NT might produce unpredictable results.

Many of these tools are designed to work only if you have logged on as a member of an Administrators group.

Most of these tools are for use on the SMS server, not on SMS clients. None of these tools are for use on Windows 95 or any other platforms.

Feedback

You can send feedback, comments, or bug reports for these tools, or for any Resource Kit documentation, to RKINPUT@MICROSOFT.COM on the Internet.


Categories of Tools

The tool descriptions are organized into the following categories:

  • System setup tools
  • Administration tools
  • Troubleshooting tools
  • Windows NT–based tools
  • Job and client tools

The tools in each category are as follows:

System Setup Tools

  • CHECKRAS.EXE: RAS Connection Checker
  • COPYVT.BAT: Visual Test 4 Installer
  • SMS_NT_INVENTORY_FILE_COLLECTOR: Inventory File Collector
  • SMGENIE.EXE: Event Log Repeater
  • SMSADDIN.EXE: Application Adder
  • SMSBOOT.EXE: Remote Windows NT Rebooter
  • TRAPMON.EXE: SNMP Trap Monitor
  • Remote Site Setup and Upgrade

Administration Tools

  • ACCTCHG.EXE: Account Changer
  • CHECKSMS.SQL: Status and Configuration Reporter
  • DELMIF.EXE: Delete-MIF File Creator
  • DUMPSYNC.EXE: Resync-File Cleaner
  • FILETOKN.EXE: File Token Generator
  • ISMIF16.EXE and ISMIF32.EXE: Status MIF Creator
  • MIFNAME.EXE: MIF File Renamer
  • NEWSVCAC.EXE New Service Account Creator
  • NLSMSG*.EXE: NLS Message Maker
  • PDFWIZ.EXE: PDF Wizard
  • PGCSET32.EXE: PGC Status Setter
  • RSAPPCTL.EXE: Shared Applications Database Resetter
  • SETCLCFG.EXE: Client Configuration Setter
  • SETGUG.EXE: Global User Group Setter
  • SKIPINV.EXE: Inventory Skipper
  • SMSMAINT.SQL: Database Maintainer
  • SQLPWD.EXE: SQL Password Changer
  • UGMIF.EXE: User Group MIF Creator
  • WRITEPDF.EXE: PDF Writer
  • WRITEQDF.EXE: QDF Writer and Reader
  • ZAP.EXE: File Zapper

Troubleshooting Tools

  • BUGDATA.EXE: Bug Data Collector
  • DUMPSEND.EXE: Display Send Request
  • ERROR32.EXE: Error Code to Message
  • FILEMOVE.EXE: File Mover
  • FIPERF.BAT: Add File Counters to Performance Monitor
  • HCOMP.EXE: Package File Compressor
  • HDECOMP.EXE: Package File Decompressor
  • HVALCOMP.EXE: Compressed Package File Validator
  • MIFCHECK.EXE: MIF Checker
  • MIPERF.BAT: Add MIF File Counters to Performance Monitor
  • NADRESET.BAT: NAD Resetter
  • NADUSER.EXE: NAD User
  • PCMDUMP.EXE: PCM Dumper
  • RAWCHECK.EXE: RAW Checker
  • SENDCODE.EXE: Send Code
  • SMSTRACE.EXE: SMS Log File Viewer
  • TRACER.EXE: Text File Viewer
  • VIEWNAD.EXE: NAD Viewer

Windows NT–based Tools

  • KILL.EXE: Task Killer
  • REGLIST.EXE: Registry List
  • RSERVICE.EXE: Service Remote Control
  • SHRPERM.EXE: Set Share Permissions
  • SRVINFO.EXE: Server Info
  • SVCCTRL.EXE: Service Manager (formerly INSTSRV.EXE)
  • TESTNET.EXE: Network Tester
  • TLIST.EXE: Task List

Job and Client Tools

  • ASSETMIF.EXE: Asset MIF Maker
  • BADPENT.EXE: Bad Pentium Detector
  • BREAKFTM.EXE: Mirror Breaker and Restorer
  • CLIOPTS.EXE: Client Options Setter
  • EXECUTE.EXE: Application Executor
  • FERRET.EXE: Compaq Info
  • ISIDIS.EXE: IDIS_NT Checker
  • NETBOOT.EXE: Network Boot Disk Generator
  • NWATTRIB.EXE: NetWare Sharable Attribute Setter
  • REMFPROT.EXE: F-PROT TSR Remover


System Setup Tools


CHECKRAS.EXE: RAS Connection Checker

CHECKRAS indicates how many Microsoft Remote Access Service (RAS) connections are currently open. When CHECKRAS is run, it returns one of the following return codes:

0 = No RAS connections

1 = 1 or more RAS connections

These return codes can be used when CHECKRAS is used in a batch file. For example, CHECKRAS can be used as part of the network logon script to detect whether the user is logged on using RAS. The usual SMS logon processes, such as inventory collection, can then be skipped if the connection is via RAS (that is, if the return code is 1). Such a logon script would include the following lines:

:CHECKRAS

CHECKRAS > nul

if errorlevel 1 goto END

REM normal logon steps here ...

:END

RAS must be installed on any computer that runs CHECKRAS.

Runs On

Alpha, x86

Files Required for CHECKRAS

CHECKRAS.EXE
RASAPI32.DLL

checkras Syntax

Checkras


COPYVT.BAT: Visual Test 4 Installer

COPYVT.BAT copies the Visual Test 4.0 runtime files to site servers so that other tools that use these files will have access to them.

The Visual Test 4.0 script requires four files: mtrun.exe, mstest40.dll, msvcrt40.dll, and loger2nt.dll. There are different versions for each platform (Alpha, x86). To run compiled Visual Test 4.0 scripts on a site's clients, these files must be copied (manually or using a Run Command on Workstation job) to the maincfg.box\mstest directory of the site.

SMS then copies them to logon.srv\mstest on all SMS logon servers, where Package Command Manager (PCM) will access them. When you run a PCM job on the client, PCM goes to its own site's logon servers' logon.srv\mstest directory for the mstest files. This is also true if the job came from a site server higher in the hierarchy.

Because the mstest files are not automatically replicated down a hierarchy, you must copy them to every site that needs them. The platform of the files to copy to a current site should be the same as the platform of the clients that will use them; it does not depend on the platform of the current site. You should then copy the x86 files to the site (overwriting the Alpha files) and use them to install all the x86 sites you want. Then copy the Alpha files to the site (overwriting the x86 files) and use them to install all the Alpha sites you want. An Alpha client must find the Alpha files on its site server, even if its site server is x86.

The overwriting is necessary because PCM does not look in the platform subdirectories of mstest; it looks only in mstest itself. To copy the files using a Run Command on Workstation job, import copyvt.pdf to create a workstation package whose source directory is the VT40run directory from the Resource Kit CD-ROM, and which also contains copyvt.PDF.

You must add \\server\share to the end of the command line in the package, where server is the site to which the client is attached, and share is the main SMS directory. SMS always shares the main SMS directory as sms_shr x, where x is the drive on which SMS is installed. You can see which drive it is on (and thus determine the share name) by looking in the SMS Administrator's Site Properties window. For example, if SMS is installed on drive d: of \\myMachine, the argument would be \\myMachine\sms_shrd.

Note In copyvt.pdf, the command line Copy Visual Test files to serverA should be used first; it copies the VT files for all platforms to the site's platform subdirectories under the mstest directory, then copies the client platform to the mstest directory itself. Change serverA to the name of your site server, and modify \\server\share as described above. If you want to use the package for more than one site, repeat for serverB. Add more as needed.

Once all platforms are on the site, you can use the other type of command line, such as Copy VT ALPHA files to serverA MSTEST dir, to copy another platform's VT files from its subdirectory to the MSTEST directory. Change serverA to the name of your site server, and modify \\server\share as described above.

Runs On

Alpha, x86

Files Required for COPYVT

ALPHAVT.BAT
COPYVT.BAT
COPYVT.PDF
LOGER2NT.DLL
MSTEST40.DLL
MSVCRT.DLL
MTRUN.EXE
X86VT.BAT


SMS_NT_INVENTORY_FILE_COLLECTOR:Inventory File Collector

SMS_NT_INVENTORY_FILE_COLLECTOR:
Inventory File Collector

SMS_NT_INVENTORY_FILE_COLLECTOR is a service that collects inventory files from clients. You can run SMS_NT_INVENTORY_FILE_COLLECTOR on SMS logon servers to collect inventory files from clients that are not logged on frequently enough to ensure accurate site database updating. (Normally, inventory files are collected from a client each time a user logs onto the client.) The clients from which to collect are specified in an initialization file, INVCOLCL.TXT.

SMS_NT_INVENTORY_FILE_COLLECTOR must run under a user account (such as the SMS service account) that has rights to administrative shares on all clients from which it is collecting inventory files.

Installing: INSTPOLL.EXE

INSTPOLL.EXE installs SMS_NT_INVENTORY_FILE_COLLECTOR on x86-based computers. For Alpha computers, use the following procedure:

To install the inventory file collector on Alpha computers

On the SMS 1.2 logon server on which you wish the service to run, copy the following files to installation directory\helper.srv\alpha.bin, or to the directory of your choice:

  • POLLINV.EXE
  • POLLREG.EXE
  • REMVPOLL.EXE

Find and note the installation directory value in the registry key

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\SMS\Setup

Create the following key in the registry:

HKEY_LOCAL_MACHINE\
SOFTWARE\
Microsoft\
SMS\
TRACING\
SMS_NT_INVENTORY_FILE_COLLECTOR

The key SMS_NT_INVENTORY_FILE_COLLECTOR must have precisely this spelling, since this is the name of the service that will be created.

Define a value, TraceFilename, in the key SMS_NT_INVENTORY_FILE_COLLECTOR. This value is used to provide the Inventory File Collector with the path of its log file. Assign it the value installation directory\LOGS\invcolcl.log, where installation directory is the pathname of the installation directory, followed by the path of the log file.

In the key SMS_NT_INVENTORY_FILE_COLLECTOR, give Enabled a value of 1.

In the key SMS_NT_INVENTORY_FILE_COLLECTOR, set the Poll Interval value to the number of hours you want between inventory collections. The default is 24.

Install the service with the following command:

pollreg.exe -path pollinv_path -serviceacct service_acct -password password

where

pollinv_path

is the absolute path of POLLINV.EXE

service_acct

is the name of the SMS service account

password

is the password on the SMS service account

For example, if POLLINV.EXE is in the directory C:\SMS\Helper.srv\Alpha.bin and the service account name is myservacct with the password mypasswd, the command would be:

pollreg -path C:\SMS\helper.srv\alpha.bin\pollinv.exe -serviceacct myservacct -password mypasswd

Deregistering: REMVPOLL.EXE

REMVPOLL.EXE deregisters SMS_NT_INVENTORY_FILE_COLLECTOR (removes it from Windows NT Service Control Manager [SCM]). SMS_NT_INVENTORY_FILE_COLLECTOR and all its files remain on the computer, but SCM does not consider it an active service.

Deregistering is useful if you want to register SMS_NT_INVENTORY_FILE_COLLECTOR with the SCM under a new account name or password, which you would do if you changed the name or password of the SMS service account.

Reregistering: POLLREG.EXE

POLLREG.EXE reregisters SMS_NT_INVENTORY_FILE_COLLECTOR with SCM on x86-based computers. For Alpha computers, use the procedure provided under Installing: INSTPOLL.EXE.

Runs On

Alpha, x86

Files Required for SMS_NT_INVENTORY_FILE_COLLECTOR

INSTPOLL.EXE
INVCOLCL.TXT
POLLINV.EXE
POLLREG.EXE
REMVPOLL.EXE

Syntax for Installing and Starting SMS_NT_INVENTORY_FILE_COLLECTOR

instpoll net start SMS_NT_INVENTORY_FILE_COLLECTOR

Syntax for Deregistering and Reregistering SMS_NT_INVENTORY_FILE_COLLECTOR

remvpoll pollreg -serviceacct "account" -password "password" -path "POLLINV_path"

-serviceacct "account"

Specifies the new SMS service account under which SMS_NT_INVENTORY_FILE_COLLECTOR will run.

-password "password"

Specifies the password for account.

-path "POLLINV_path"

Specifies the path for POLLINV.EXE.

Registry Entries for SMS_NT_INVENTORY_FILE_COLLECTOR

A polling interval for SMS_NT_INVENTORY_FILE_COLLECTOR can be specified through the PollInterval in the following registry key:

HKEY_LOCAL_MACHINE\
SOFTWARE\
Microsoft\
SMS\
Components\
SMS_NT_INVENTORY_FILE_COLLECTOR

PollInterval is of type REG_DWORD and specifies the polling interval in hours. The default is 24.

Administrator privilege is required to change this value. Changes are not sent to SMS_NT_INVENTORY_FILE_COLLECTOR; changes are picked up at the end of each processing cycle. Therefore, a change in the registry takes effect for the next interval between processing cycles but does not cause the service to wake up and start a new processing cycle.

INVCOLCL.TXT: the SMS_NT_INVENTORY_FILE_COLLECTOR Initialization File

A file containing a list of clients to be processed by SMS_NT_INVENTORY_FILE_COLLECTOR must be located in SMS\SITE.SRV\MAINCFG.BOX\CLIENT.SRC\INVCOLCL.TXT on the SMS site server on which SMS_NT_INVENTORY_FILE_COLLECTOR is run. INVCOLCL.TXT will be copied to all SMS logon servers by Maintenance Manager.

INVCOLCL.TXT contains one client per line. Lines starting with semicolons (;) or pound signs (#) are ignored. The list can be separated into sections. Each section is named for the computer that will collect the inventory from the clients in that section. Section names are surrounded by brackets. For example, consider the following INVCOLCL.TXT:

ClientA
ClientB
[Server1]
ClientC
ClientD
[Server2]
ClientE
[Server3]

The SMS_NT_INVENTORY_FILE_COLLECTOR service running on Server1 collects inventory from ClientA, ClientB, ClientC, and ClientD.

The SMS_NT_INVENTORY_FILE_COLLECTOR service running on Server2 collects inventory from ClientA, ClientB, and ClientE.

The SMS_NT_INVENTORY_FILE_COLLECTOR service running on Server3 collects inventory from ClientA, and ClientB. The section for Server3 is unnecessary.


SMGENIE.EXE: Event Generator

SMGENIE generates events that simulate actual system and application events. The purpose of SMGENIE is to test the SNMP Event to Trap Translator, which converts preselected events to SNMP traps when the events are written to the Windows NT Event Log.

After SMGENIE is started, the SMGENIE window appears on your screen.

Runs On

Alpha, x86

Files Required for SMGENIE

SMGENIE.EXE

SMGENIE Syntax

smgenie

Using SMGENIE

Once SMS is installed and the SNMP components are set up, you can configure the SNMP Event to Trap Translator with the events to be translated (see the SMS Administrator's Guide). Then use SMGENIE to generate events to the Windows NT event log; events that have been set in the SNMP Event to Trap Translator will be translated into traps and sent to the site server.

To Generate Events with SMGENIE

Select an event log from the Event Logs box.

Select an event source from the Event Sources box.

The events for the selected event source are displayed in the list at the top of the window. The number of events available in the event source are displayed in the Event Count box.

You can use the Auto Search box to locate an event source among all the event logs. In the Auto Search box, type the name of a source.

Select events by scrolling through the list and clicking on them.

SHIFT CLICK and CTRL CLICK can be used to select ranges and multiple events. The number of selected events is shown in the lower-right status bar.

Change the default Sub-string, if necessary. The default is TEST-STRING.

The Sub-string is placed into each event wherever there is a percent sign (%) followed by a number. (In actual Windows NT event generation, subsequent numbers denote different strings. In SMGENIE, Sub-string is used regardless of the number following the percent sign.)

Generate events in one of two ways:

  • Click Generate Events.
  • In the Auto Generate box, specify integers for Multiples and Interval in Seconds, then select Auto Generate. Multiples specifies how many events to generate for each selected event, and Interval in Seconds specifies how often to generate them, repeating until Auto Generate is no longer selected.

    For example, if Winlogon is the event source, events 1001 and 1002 are selected, and the default settings are used, selecting Auto Generate generates one of each event every five seconds. Two events are logged in the Windows NT Event Log every five seconds; one for event 1001, and one for event 1002.

The number of events generated is shown in the lower-left status bar.


SMSADDIN.EXE: Application Adder

SMSADDIN allows you to register applications so that they can be launched directly from the Tools menu in the SMS Administrator. SMSADDIN features a graphical user interface and its own Help file.

Runs On

Alpha, x86

Files Required for SMSADDIN

SMSADDIN.EXE

SMSADDIN Syntax

smsaddin..[/r file_name] [/u | /v file_name]

file_name

An .ATD file.

/r

Removes the registry structure. (The default behavior is to add to the registry.) This option permits ISVs to delete application registry entries in an unattended way. The vendor key is deleted if no other ISV applications are registered underneath it.

/u

Unattended mode. Makes SMSADDIN silent, even when file_name contains invalid data. This mode permits SMS to deploy applications unattended. This option is exclusive with /v.

/v

Verbose mode. The interface displays boxes showing the details of the registry update. Selecting the Register button (check mark) causes the application to make the call to RegisterSMSTool. This mode is intended primarily for ISVs during development. The graphical interface is not used for a customer application setup. If there are no command-line arguments, verbose mode is enabled automatically. This option is exclusive with /u.

SMSADDIN ATD File

For each tool added to the Tools menu, SMSADDIN writes an ATD file, which has this format:

[Values]

Hive=HKEY_CURRENT_USER

VendorKey=XenoSoft

ApplicationKey=Food

ApplicationName=Burger Now 3.2

Description=A description

Command=burgnow.exe

WorkingDir=c:\stuff\bin

RunWindow=Normal

Order=0

[General]

PresentRule1=

EnableRule1=

Arguments1=


SMSBOOT.EXE: Remote Windows NT Rebooter

SMSBOOT reboots a remote Windows NT computer.

Runs On

Alpha, x86

Files Required for SMSBOOT

SMSBOOT.EXE

SMSBOOT Syntax

smsboot -n:remote_computer [-d:delay] [-f] [-m:"message"] [-r]

-n:remote_computer

Specifies the NetBIOS machine name of a remote computer to reboot. The local computer cannot be rebooted by SMSBOOT.

-d:delay

Specifies the number of seconds before shutdown of the remote computer. The default is 30.

-f

Does not wait for applications with pending changes. The default is to wait for each application with a pending change.

-m:"message"

Specifies a message to be displayed on the remote computer's console. The default is "Remote shutdown initiated."

-r

Does not prompt the remote computer's console to reboot after shutdown. The default is to prompt before rebooting.

/?

Provides a usage statement.


TRAPMON.EXE: SNMP Trap Monitor

SNMP Trap Monitor allows you to check the reliability and throughput of your SNMP trap delivery system. SNMP Trap Monitor tests the delivery of SNMP traps from a trap generator to a trap receiver by comparing the number of traps sent and received.

The SNMP protocol does not support acknowledgment of sent traps, but SNMP Trap Monitor stores received traps in a database, providing a way to keep track of sent traps. Therefore, SNMP Trap Monitor must be run on at least two computers, so that the traps sent by an SNMP agent can be received, stored, and compared at all computers running SNMP Trap Monitor. All sites running SNMP Trap Monitor can see all the received traps at any other site.

To reduce network traffic, place one of the SNMP Trap Monitors at the site where the SNMP agent is sending traps; this will reduce network traffic, because traps are internally looped back. The second SNMP Trap Monitor can be placed at another site to test network reliability.

Runs On

Alpha, x86

Files Required for TRAPMON

TRAPMON.EXE
TRAPMON.INI
MGMTAPI.DLL

The following software is also required:

Microsoft ODBC (Open Database Connectivity) Driver 2.0 or higher
Microsoft SQL Server 6.0 or higher
TCP/IP and SNMP protocols
Windows NT SNMP service

Setting Up SNMP Trap Monitor

The following procedures include two instances of SNMP Trap Monitor and one of SNMP agent. Before starting either procedure, complete the following steps:

Install TCP/IP and SNMP protocols on all computers that will run SNMP Trap Monitor. Because SNMP Trap Monitor uses the PUBLIC community, be sure the SNMP protocol's security is set up to receive traps from the PUBLIC community, which is the default.

Install TCP/IP and SNMP protocols on the monitored computer that will be transmitting traps. Set up the SNMP protocol on this computer to send traps to all computers running SNMP Trap Monitor using the PUBLIC community.

Install ODBC on all computers that will run SNMP Trap Monitor. ODBC must point to the computer running SQL Server, in which SNMP Trap Monitor will create its trap database. The name of the database that will be created is specified in the initialization file.

Create or modify an initialization file.

To Set Up SNMP Trap Monitor on a Local and a Remote Site

In this procedure, one SNMP Trap Monitor runs on the monitored node, which is the local computer running the SNMP agent, while the second SNMP Trap Monitor runs on a remote computer.

Setup the SNMP agent in Control Panel on the local site to send traps to itself and the remote SNMP management console.

Run the following command on both the local and remote computers:

trapmon.exe TRAPMON.INI

Transmit traps to the local and remote computers.

To Set Up SNMP Trap Monitor on Two Remote Sites

In this procedure, neither instance of SNMP Trap Monitor runs on the monitored node, which is the local computer running the SNMP agent.

Setup the SNMP agent in Control Panel at the monitored node to send traps to both remote SNMP management consoles.

Run the following command on both remote computers:

trapmon.exe TRAPMON.INI

Transmit traps to both remote computers.

The SNMP Trap Monitor GUI

Shortly after running the TRAPMON.EXE command, the SNMP Trap Monitor GUI appears. This window includes the following items:

  • The white area at the top is the list of traps in the database, if any. Each record in this list is composed of the following fields, left to right:
    • IDENTICAL or MISMATCH. When two or more SNMP Trap Monitors are running, this field shows whether the traps received by all computers are identical—which they should be—or whether there is a mismatch.
    • EventInfo. The event source and event ID.
    • Agent. The IP address of the computer that sent the trap.
    • Names of all computers running SNMP Trap Monitor, followed by the number of traps they have received. When an additional computer runs SNMP Trap Monitor and receives a trap, another column with that computer's name and number of traps received is appended to that trap's record.

No new data is shown until you click Refresh.

  • Monitored Node. This box shows the computer being monitored, which was specified in the initialization file.
  • Traps Updated. Shows how many traps have been received at the computer running SNMP Trap Monitor, regardless of the trap type.
  • Trap Types. Shows how many different types of traps have been received at the computer running the SNMP Trap Monitor.
  • Action on new traps. If Write is selected, traps sent from the monitored node are written to the database and the Traps Updated counter is incremented. If the trap received is a new type of trap that does not exist in the database, the Trap Types counter is incremented. If Discard is selected, traps sent from the monitored node are not written to the database. Neither the Traps Updated nor the Trap Types counters change.
  • New Traps Queued. This counter is incremented each time a new trap arrives at the computer running SNMP Trap Monitor.
  • Reset. Clears the database of all traps and sets the New Traps Queued, Traps Updated and Trap Types counters to 0.
  • Refresh. Updates the list to include any new data since the last refresh.
  • Quit. Quits SNMP Trap Monitor.

Usage Strategies

This section outlines some ways to use SNMP Trap Monitor.

Connectivity Testing

Connectivity can be tested by low quantity, timed, controlled event logging. You can confirm the receipt of traps sent from an SNMP agent to an SNMP management console. Problems can be caused by network topology or network configuration.

Data Saturation Testing

A network storm can be simulated by large quantity, untimed, uncontrolled event logging. You can determine if there are any network or SNMP bottlenecks.

Frequency, Threshold, and Throughput Testing

You can generate a certain number of events per second to determine at what frequency traps fail to be received at an SNMP management console. This determines the maximum number of traps that can be reliably sent for a given agent-manager connection.

Connection Saturation Testing for Frequency and Delay

You can generate a number of events per second used in the previous test, then wait. This determines if the receiver at the SNMP management console is able to handle traps received at a constant rate.

Testing Whether a Trap is Lost or Stalled

When sending many traps at once, sometimes not all of them are received; they are either lost or stalled. Wait a few seconds, then send one more trap. If the missing traps were stalled, they will show up with the latest trap.

For example, you send 100 traps at once, but only 98 are received. You then send one more trap and three are received; the missing two traps were merely stalled, not lost.

Troubleshooting

This section offers various suggestions for solving problems.

  • Try restarting the Windows NT SNMP services on all management and agent consoles.
  • Make sure that communities and hosts are set up correctly in the control panels.
  • Make sure that the security feature in Control Panel is set up correctly.
  • Make sure that the SNMP agent is set up correctly. End-to-end and applications check boxes must be checked in Control Panel on the computer running the SNMP agent.
  • Make sure the contents of the initialization file are correct.
  • Make sure the appropriate radio button (Write or Discard) is selected in SNMP Trap Monitor.
  • If you send one trap but received two, make sure you do not have two SNMP communities with the same host name; check Control Panel.
  • If you do not receive traps, try making an IPC$ connection to the data source.
  • Any changes made to the Windows NT SNMP service in Control Panel will not take effect until after the SNMP service is restarted.
  • When using the Event to Trap Translator, if Windows NT events are logged but no traps are sent, make sure the event log is not full. If it is full, clear the event log or set it to overwrite old events.
  • Make sure the database named in the initialization files at all computers running SNMP Trap Monitor is the same.

Other Tools to use with SNMP Trap Monitor

Network Monitor

Network Monitor can determine where traps are being dropped in a network, as well as trace problems with network configuration and network devices.

Windebug

Windebug can debug the SNMP extension agents and SNMP management console applications.

SMGENIE

SMGENIE generates events, which the SNMP Event to Trap Translator can convert to traps, which will be forwarded to the SNMP Trap Monitor.

SNMP Event to Trap Translator

The SNMP Event to Trap Translator (see the SMS Administrator's Guide) converts Windows NT system and application events (events written to the Windows NT event log) into SNMP traps.

TRAPMON Syntax

trapmon [init_file]

init_file

A TRAPMON initialization file. The default is TRAPMON.INI in the current directory.

TRAPMON Initialization File

Node_ID RES RES RES ODBC_data_source ODBC_table ODBC_user_ID [ODBC_password]

The TRAPMON initialization file (default name TRAPMON.INI) has one record of the preceding form. The fields in this record have the following meanings:

Node_ID

A computer name without backslashes (for example, node5), or a dotted IP address (for example, 172.918.3.14)

RES

These are reserved for future use. Specify the value 1.

ODBC_data_source

The name of an ODBC (Open Database Connectivity) data source to which you can direct logged data.

ODBC_table

The name of a table within ODBC_data_source to which you can direct logged data. If this table does not exist, TRAPMON creates it.

ODBC_user_ID

The user ID used for connecting to ODBC_data_source.

ODBC_password

The password used for connecting to ODBC_data_source.

Notes on SNMP Trap Monitor's Behavior

Because SNMP traps are transmitted using the User Datagram Protocol (UDP), there are limitations on them that affect the operation of SNMP Trap Monitor:

  • SNMP traps are not guaranteed to be delivered, and there is no notification if they are not.
  • Most network stack implementations and routers limit the size of UDP packets. If the packet is too large, the router drops it and records it as a discarded packet. Because many of the SNMP traps generated from Windows NT events are larger that the usual limits on UDP packets, many of these traps will not be delivered to SNMP consoles over a routed network.

SNMP Trap Monitor provides what the SNMP protocol lacks: an artificial means of acknowledging traps sent using the UDP.

SNMP Trap Monitor also provides a means of determining the reliability of SNMP trap transmission, taking into account the following:

  • Transmission frequency
  • Quantity of traps transmitted and received
  • Reliability during network storms
  • Transmission thresholds
  • Network topology
  • Network configuration
  • Uses of other tools in conjunction with SNMP Trap Monitor


Remote Site Setup and Upgrade

This utility allows you to install or upgrade a primary site using Package Command Manager.

Runs On

x86, Alpha

Files Required for Remote Site Setup and Upgrade

ADDRESS.INI
BVTDLG.PCD
cpy2root.pdf
SITES.PDF
SU.INI
UPDPROXY.BAT
UPGRADE.PCD

Copying Files with cpy2root.pdf

CPY2ROOT.PDF copies all files from root of the source directory to the root of c: on the client from which the PCM job is run. CPY2ROOT.PDF copies SU.INI and other files to the client before running a remote SMS installation job, which expects the files to be there.

Installing a Primary Site Using Package Command Manager

Note The computer on which you want to install an SMS site must currently be a client, and it must meet the requirements for primary site servers, as specified in SMS Getting Started.

Modify the initialization file, SU.INI, to include all the data needed to install the site.

Copy SU.INI to the client's c:\ root manually, or use a Run Command on Workstation job to copy it there. (The initialization file must be on c:\ and must be named SU.INI).

Modify and copy updproxy.bat to c:\ if you want the proxies to be copied automatically to their administrative installations.

Modify address.ini to include any addresses you want created, and place address.ini at the location you specified in SU.INI.

You can import CPY2ROOT.PDF to create a workstation package whose source directory contains su.ini and updproxy.bat.

The program to install SMS remotely (BVTDLG.PCD) carries out the following tasks if their keys are specified in su.ini:

  • Installs SMS
  • Copies proxy applications to an administrative installation of an application
  • Sets licensing, tracing file sizes, SMS Administrator defaults, and some site properties
  • Adds domains, package servers, and addresses
  • Attaches to a parent
  • Initiates the installation of secondary sites
  • Creates packages, queries, machine groups, program groups, site groups, and alerts
  • Creates jobs to compress and send packages (no instruction files)

Ensure that the client's site server has the MSTEST files. (COPYVT.PDF automatically copies the appropriate files.)

Import sites.pdf to create a workstation package whose source directory contains the sms source files and bvtdlg.pcd. Choose the command line Create new site. The smssetup directory must be exactly one level down from the root of the source directory; for example, c:\sms12\smssetup, with bvtdlg.pcd placed in sms12, and c:\sms12 specified as the source directory.

If you also include upgrade.pcd in the source directory, you can use the same package for installing new sites and for upgrading existing sites. Because the source directory is large, using the same package saves much disk space.

If you are sending the package from site A to install a site on a client of A, the procedure is the same as for any Run Command on Workstation job. When you are sending the package from site A to upgrade site B, which is lower in the hierarchy, proceed as follows:

Create a Run Command on Workstation job to send the package to site B (which need not be a default distribution server of site A).

In the job, under Put on Specified Distribution Servers, select Default Servers. The job will appear as a workstation package on the default distribution servers of site B (not site A) and can be run from the client of site B.

Upgrading a Primary Site Using Package Command Manager

Note Neither su.ini nor updproxy.bat is needed to upgrade a site using the following method.

Ensure that the site server to be upgraded has the mstest files. Because the client running the upgrade package is the site server itself, you must always send the files corresponding to the platform being upgraded; for example, if you are upgrading an x86 site, send the x86 mstest files. (COPYVT.PDF automatically copies the appropriate files.)

Import sites.pdf to create a workstation package whose source directory contains the sms source files and upgrade.pcd.

Choose the command line Upgrade existing site. The smssetup directory must be exactly one level down from the root of the source directory; for example, c:\sms12\smssetup, with upgrade.pcd placed in sms12, and c:\sms12 specified as the source directory.

If you also include bvtdlg.pcd in the source directory, you can use the same package for installing new sites and for upgrading existing sites. Because the source directory is large, using the same package saves much disk space.

When you are sending the package from site A to upgrade site A, the procedure is the same as for any workstation job . When you are sending the package from site A to upgrade site B, which is lower in the hierarchy, proceed as follows:

Create a Run Command on Workstation job to send the package to site B (which need not be a default distribution server of site A).

In the job, under Put on Specified Distribution Servers, choose Default Servers. The job will appear as a workstation package on the default distribution servers of site B (not site A) and can be run from site B.

If disk space is a concern, do not choose Default Servers. Instead, create a machine group with the minimum number of distribution servers needed to reach all sites.

Initialization File

This topic lists SMS initialization file parameters commonly used in SU.INI. This topic contains one subtopic for each section in SU.INI. The SU.INI file is used in the SMS test team's build verification and test (BVT), the BackOffice SMS install and verification script, and in other SMS testing. su.ini is commonly found in the root of the C: or D: drive.

Important Although the scripts check some of the values in SU.INI, you must ensure that SU.INI contains valid values.

SKIP means use the default. In some cases, such as SQL Server information, you might have to specify values.

To add a comment to SU.INI, start a line with an apostrophe (') or semicolon (;). You cannot put a comment on the same line as a non-comment.

SU.INI Sections

SQL Server
Setup
Parent
Parameters
Services
Client
Packages
Jobs
Program Groups
Machine Groups
Site Groups
Queries
Alerts
Tracing
Domains
Servers
Secondary Sites
Licensing

SQL Server

The [SQL_Server] section sets properties for an instance of SQL Server.

Replace with current SQL information. Having duplicate SQL login info under [SQL_Server] and [Setup] allows you to specify a different instance of SQL Server and account to open SMS Administrator than was used during setup

Entry | Description | Value
szSQLServer | Name of SQL Server | Server name or SKIP
szSQLDatabase | Database name | Database name or SKIP
szSQLAccount | SQL Server account name | Account name or SKIP
szSQLAccountPW | SQL Server account password | Password or SKIP

Setup

The [Setup] section sets properties for an SMS site server.

Replace with current SQL information. Having duplicate SQL login information under [SQL_Server] and [Setup] allows you to specify a different instance of SQL Server and account to open SMS Administrator than was used during setup.

Entry | Description | Value
szUserName | Name of person or owner |
szOrganization | Name of dept. or company |
szSetupName | Name of person or owner |
szSQLServer | SQL Server used |
szSQLLoginName | SQL login name |
szSQLPw | SQL password |
szDBData | SQL data device |
szDBLog | SQL log device |
szDBName | SMS SQL database name |
szSiteCode | Site code |
szSiteName | Site name |
szSiteServerDomain | Site server domain |
szServiceAcctUser | SMS administrator service account |
szServiceAcctPw | Service account password |
nAutoLogonServers | Install SMS on all logon servers in domain | 1 = yes, 0 = no
nDropDatabase | Drop existing database | 1 = yes, 0=no
nDropDevices | Drop devices, if local | 1 = yes, 0=no
szSWInstallOptions | Select SMS components to install | all to select all available components, some to add the below selected components, or nothing for default
szIntelSrv | Select Intel Server | 1 = install
szIntelCli | Select Intel Client | 1 = install
szAlphaSrv | Select Alpha Server | 1 = install
szAlphaCli | Select Alpha Client | 1 = install
szScripts | Select Scripts | 1 = install
szBooks | Select SMS Online Books | 1 = install
szNetMon | Select Network Monitor | 1 = install
szSMSAdmin | Select SMS Administrator | 1 = install
SzMacCli | Select Macintosh Client | 1 = install

Parent

The [Parent] section sets a site to be standalone, or sets a parent site code.

Entry | Description | Value
nSiteParentStandAlone | Standalone site or has parent | 1 = standalone, 2 = has parent
szSiteAttachToParentSiteCode | Parent site code, if not standalone | Three-character site code in uppercase

Note If you set the parent site, you must also set the parent address in address.ini.

Parameters

The [PARMS] section sets miscellaneous setup and logging properties.

Entry | Description | Value
gszLogServer | Server to log files to; use drive letter; for example C: | A: to Z: for local server. L: for remote server
gszLogDir | Directory to log files. If gszLogServer already points to the right place, (L: points to \\machine\logs) then leave this entry empty |
szSMSShare | Location of SMS CD-ROM or share (\\server\share). Must use UNC path | \\server\share
installpath | Path to where you want SMS installed | d:\smscentral
gszAddressFile | File with addresses of other sites | c:\smsvtst\address.ini
szToolsShare | Location of sendcode.exe and other utilities from the CD-ROM | \\server\share
szWaitForNetware | Wait for NetWare server to appear in inventory | yes or no
szMacPath | Location of the Macintosh Installer if the Macintosh client components are installed | \\server\share\dir

Services

The [Services] section sets some server services properties.

Entry | Description | Value
nModifySiteServicesSpeed | Modifies the service polling intervals. Only very small sites with one or two logon servers should use 1. 1=very fast (polling interval 1 min), creates a very heavy server load 2=fast, creates a heavy server load 3=medium, creates a moderate server load 4=slow, creates a light server load | 1 to 4

Client

The [Client] section sets some client properties.

Entry | Description | Value
nSiteClientsAutoConfigLogon Scrp | Auto logon script: | enabled=1, disabled= 0
nSiteClientsInsertLogon | Insert logon script: | top=1, bottom=2
szSiteClientsPcmPollingIntrvl | Client polling interval for workstation installation jobs, in minutes | 5-60

Packages

There are three types of packages: inventory, workstation installation, and shared packages. Each package has different parameters. Each package has its own section: [PKG n].

Entry | Description | Value
fImportPDF | SMS ships with some PDFs (Program Definition Files) | False or 0 = no import; True or -1 = import PDF
szImportPDF | PDF filename to import |
szWksPkgSrcDir | For Import, source directory of package's files. |
SzPkgName | Package name |
szPkgComm | Package comment |
nInventoryPkg | Inventory package | 1 = yes
nInvCount | For inventory package, the number of inventory rules | The product currently supports only 1

Inventory packages have an additional section: [PKG n_INV x].

Entry | Description | Value
szAndOr | AND/OR condition | AND or OR
szFileName | File to be inventoried | Name of file
nCollectFile | Collect inventoried file? | 1=yes, 0=no

Workstation packages also have an additional section: [PKG n_WKS x].

Entry | Description | Value
szWKSPkgCommName | Command name |
szWKSPkgCommLine | Command line |
nWksChkAuto | Automated cmd line | 1=yes, 0=no
nWksChkBackGnd | Background task | 1=yes, 0=no
nWksPlDOS | Platform to run on | 1=yes, 0=no
nWksPlWin | Platform to run on | 1=yes, 0=no
nWksPlWin95 | Platform to run on | 1=yes, 0=no
nWksPlNTX86 | Platform to run on | 1=yes, 0=no
nWksPlNTAlpha | Platform to run on | 1=yes, 0=no

Examples

[PKG1]

fImportPDF=False

szPkgName=Inventory CONFIG.SYS

szPkgComm=This package collects all instances of the file CONFIG.SYS.

nInventoryPkg=1

nInvCount=1

[PKG1_INV1]

szAndOr=AND

szFileName=CONFIG.SYS

nCollectFile=1

[PKG2]

fImportPDF=0

szPkgName=Foo Batch File Package

szPkgComm=Package containing the file foo.bat.

szWksPkgSrcDir=c:\foo

nWksCount=1

[PKG2_WKS1]

szWKSPkgCommName=foo batch file

szWKSPkgCommLine=foo.bat

nWksChkAuto=0

nWksChkBackGnd=0

;platforms to run on, 1 is TRUE

nWksPlDOS=1

nWksPlWin=1

nWksPlWin95=1

nWksPlNTX86=1

nWksPlNTAlpha=1

[PKG3]

fImportPDF=-1

szImportPDF=enu\wwd60c.pdf

szWksPkgSrcDir=\\hermanoid\wwd60c

[PKG4]

fImportPDF=-1

szImportPDF=enu\EXC50C.PDF

szShrPkgSrcDir=\\hermanoid\exc50c

szShrPkgShareName=work\exc50ash

[PKG5]

fImportPDF=-1

szImportPDF=enu\msapps.pdf

szShrPkgSrcDir=\\hermanoid\msapps

szShrPkgShareName=work\msappssh

[PKG6]

fImportPDF=-1

szImportPDF=enu\m_exc50.pdf

szWksPkgSrcDir=\\hermanoid2\Macapps\Excel 5.0

Jobs

Each job has its own section [Job n].

Entry | Description | Value
nJobType | Job type | 1 = workstation, 2 = share, 3 = remove from server
nShrPutSpecDistSrvrs | Put on specified servers | 0 = No, 1 = Yes
nShrRefExistingDistSrvrs | Refresh existing servers | 0 = No, 1 = Yes
nShrSendPackage | Send if | 1 = Only if not previously sent, 2 = Even if previously sent
nWksJobTarget | Job target source type | 1 = query, 2 = machine group, 3 = machine path
nWksJobTargetString | Job target source name | Machine path (*|*|* means all machines), query name, machine group name
szComment | Comment |
szPackageName | Package name |

Example

[Job1]

JobType=2

szComment=Compress and Distribute Excel 5.0c

szPackageName=Excel 5.0c

nShrSendPackage=2

nShrRefExistingDistSrvrs=0

nShrPutSpecDistSrvrs=1

[Job2]

nJobType=2

szComment=Compress and Distribute MSAPPS 2.0

szPackageName=MSAPPS 2.0

nShrSendPackage=2

nShrRefExistingDistSrvrs=0

nShrPutSpecDistSrvrs=1

[Job3]

nJobType=1

szComment=Compress and Distribute Foo Batch File Package

szPackageName=Foo Batch File Package

nWksSendPackage=2

nWksRefExistingDistSrvrs=0

nWksPutSpecDistSrvrs=1

nWksWrkStnCmd=0

[Job4]

nJobType=1

szComment=Compress and Distribute Word for Windows 6.0c

szPackageName=Word for Windows 6.0c

nWksSendPackage=2

nWksRefExistingDistSrvrs=0

nWksPutSpecDistSrvrs=1

nWksWrkStnCmd=0

[Job5]

nJobType=1

szComment=Compress and Distribute Excel for Mac

szPackageName=Excel 5.0

nWksSendPackage=2

nWksRefExistingDistSrvrs=0

nWksPutSpecDistSrvrs=1

nWksWrkStnCmd=0

Program Groups

Program groups are needed for shared packages to work on the client. Each program group has its own section [PGroup n].

Entry | Description | Value
szPrgName | name |
szPrgCmnt | comment |
szUsers | user groups to be added. Add the Everyone user group if you have NetWare domains. | Names separated by tildes (~)
szPackages | Package names | Names separated by tildes (~)

Example

[PGroup1]

szPrgName="SMS BKOFF"

szPrgCmnt=Without Comment

'Add Everyone user group if you have Netware domains.

szUsers=Domain Admins~Domain Users~Domain Guests~

szPackages=Excel 5.0c~MSAPPS 2.0~

Machine Groups

Each machine group has its own section [MGroup n].

Entry | Description
szMachName | Group name
szMachCmnt | Comment

Example

[MGroup1]

szMachName = All machines

szMachCmnt = All machines at the site except NetWare servers

[MGroup2]

szMachName = Windows NT Clients

szMachCmnt = All clients that should get their software from the Windows NT server

[MGroup3]

szMachName = NetWare Clients

szMachCmnt = All clients that should get their software from the NetWare server

[MGroup4]

szMachName = Windows NT Server

szMachCmnt = The Windows NT Server at this site

[MGroup5]

szMachName = NetWare server

szMachCmnt = The NetWare server at this site

[MGroup6]

szMachName = BackOffice SMS test clients

szMachCmnt = Test clients for jobs

Site Groups

Each site group has its own section [SGroup n].

Entry | Description
szSiteName | Name
szSiteCmnt | Comment

Each site group has its own section for adding members: [SGAdd n].

Entry | Description
szGroup | Target name
szSite | Site name to be added

Example

[SGroup1]

szSiteName = Site server only site group

szSiteCmnt = A comment for the site group

[SGAdd1]

szGroup = Site server only site group

szSite = BVT Primary Site

Queries

Each query has its own section: [Query n]. Each query expression has its own section: [Query n_Exp n].

Entry | Description
szQuery | Name Name
szQueryArch | Query architecture
nQueryExpCount | Number of expressions

Example

[Query1]

szQueryName=All machines not at site FOO

szQueryArch=Personal Computer

nQueryExpCount=1

[Query1_Exp1]

szExpAndOr=And

szExpGroup=Identification

szExpAtt=Site

szExpOperator=IS NOT

szExpValue=FOO

[Query2]

szQueryName=Group Everyone

szQueryCmnt=Wait for Program groups from NetWare

szQueryArch=UserGroups

nQueryExpCount=1

[Query2_Exp1]

szExpAndOr=And

szExpGroup=Identification

szExpAtt=UserGroup

szExpOperator=IS

szExpValue=EVERYONE

Alerts

Each alert has its own section: [Alert n].

Entry | Description
szAltName | Name of alert
szAltQuery | Name of query
szAltCmnt | Comment
szAltRepeat | Minutes between repeating
iAltLog | Log an event
iAltNotify | Notify computer or user
szAltNotifyName | Name to notify

Example

[Alert1]

szAltName=New Machine Alert

szAltQuery=All machines not at site foo

szAltCmnt=Test alert

szAltRepeat=10

iAltLog=1

iAltNotify=1

szAltNotifyName=hermbvt

Tracing

The [Tracing] section sets SMS log sizes.

Example

[Tracing]

SqlEnabled=1

SMS_ALERTER=1000000

SMS_APPLICATIONS_MANAGER=1000000

SMS_ASYNC_RAS_SENDER=1000000

SMS_BATCH_SNA_SENDER=1000000

SMS_DESPOOLER=1000000

SMS_EXECUTIVE=1000000

SMS_HIERARCHY_MANAGER=1000000

SMS_INTER_SNA_SENDER=1000000

SMS_INVENTORY_AGENT_NT=1000000

SMS_INVENTORY_DATA_LOADER=2000000

SMS_INVENTORY_PROCESSOR=1000000

SMS_ISDN_RAS_SENDER=1000000

SMS_LAN_SENDER=1000000

SMS_MAINTENANCE_MANAGER=1000000

SMS_PACKAGE_COMMAND_MANAGER_NT=1000000

SMS_SCHEDULER=2000000=1000000

SMS_SITE_CONFIG_MANAGER=1000000

SMS_SITE_INVENTORY_DATA_LOADER=1000000

SMS_SITE_REPORTER=1000000

SMS_SNA_RECEIVER=1000000

SMS_USER_INTERFACE=2000000

SMS_X25_RAS_SENDER=1000000

Domains

The [Domain n] section adds domains to a site.

Entry | Description | Value
szSiteDomainsName | Domain name |
szSiteDomainsType | Domain type | Microsoft Windows NT, LAN Manager, or Novell NetWare
szSiteDomainsNewLogonsrvrName | Machine;drive/volume/SKIP |
nSiteDomainsSpecified | Use all detected or specified servers | 1 = all detected, 2 = specified

Example

[Domain1]

szSiteDomainsName=h@anatdom

szSiteDomainsType=Microsoft Windows NT or LAN Manager

szSiteDomainsNewLogonsrvrName=h@anat;d

nSiteDomainsSpecified=2

Servers

The [Server n] section adds a default package server to a site.

Example

[Server1]

szServerName=h@anat

Secondary Sites

The [SecondarySite n] section installs secondary sites.

Entry | Description | Value
szNewSitePlatfrm | Platform | DEC ALPHA or INTEL X86

Example

[SecondarySite1]

szNewSiteSiteCode = EVS

szNewSiteSiteName = evan's secondary site

szNewSiteSiteSrvr = H99SITE

szNewSiteInstallDir = D:\SECSITE

szNewSiteSvrDom = H99DOM

szNewSiteUsrName = SMSPWR

szNewSitePw = password

szNewSiteCnPw = password

szNewSiteLanRasSna = LAN

szNewSiteSndrType = MS_LAN_SENDER

szNewSitePlatfrm = INTEL X86

Licensing

The [Licensing] section takes the number of licenses in the licensing application, License Manager, and writes that number to the Network Administration program.

Entry | Description | Value
szProduct | Product name | Systems Management Server v1.2
szQuantity | Number per seat | Number of licenses
szComment | Comment |

Example

[Licensing]

szProduct=Systems Management Server v1.2

szQuantity=100

szComment=Installed by Automation


Administration Tools


ACCTCHG.EXE: Account Changer

ACCTCHG changes the information that SMS services use to access the SQL Server database. ACCTCHG affects only the services on the specified site server. ACCTCHG does not make any changes to SQL Server itself; this must be done manually while running ACCTCHG:

Run ACCTCHG, specifying a site server. ACCTCHG shuts down that site and waits.

Using SQL Server tools, make whatever changes you wish; for example, change the SQL Server account and password, rename the SMS database, or move the database to another SQL Server.

Resume ACCTCHG by returning focus to the window running ACCTCHG and pressing any key.

ACCTCHG prompts you for the following information to be used from now on by the SMS services in the specified site:

  • SQL Server name
  • SQL Server database name
  • SQL Server account
  • SQL Server password

ACCTCHG restarts the site.

Runs On

Alpha, x86

Files Required for ACCTCHG

ACCTCHG.EXE

ACCTCHG Syntax

acctchg site_server [/v]

site_server

The name of the site server whose SMS services will be affected.

/v

Verbose mode. More output is displayed on the screen.


CHECKSMS.SQL: Status and Configuration Reporter

CHECKSMS.SQL provides a quick dump of data (resource usage, status, and configuration) about an SMS database and its SQL Server that can be read, saved, or pasted into records and reports. This information is helpful when troubleshooting SQL problems, planning for hardware upgrades, or restoring SQL Server or an SMS database.

CHECKSMS.SQL also provides a set of commented SQL commands that are commonly used when working with the SQL Server in an SMS hierarchy.

Runs On

Alpha, x86

Files Required for CHECKSMS

CHECKSMS.SQL

CHECKSMS Syntax

To run checksms.sql, open it in an ISQL/w command window and execute it.

Additional directions are in the checksms.sql file.


DELMIF.EXE: Delete-MIF File Creator

DELMIF deletes clients both up and down a hierarchy. DELMIF creates a delete-MIF file that deletes a client from a site database and all site databases above it.

Used in conjunction with a SQL trigger, DELMIF can be invoked automatically when a client is deleted. DELMIF can also be used to delete clients down a hierarchy by creating command files and sending them to child sites as PCMSVC jobs.

Runs On

Alpha, x86

Files Required for DELMIF

DELMIF.DLL

DELMIF.EXE

DELMIF Syntax

delmif SMSID [output_directory]

delmif @SMSID_file [output_directory]

SMSID

The SMS ID of the client to delete.

SMSID_file

A file containing several SMSIDs to be deleted, one per line. All characters after the first space on a line are ignored.

An easy way to create SMSID_file is to execute a query in the SMS Administrator (with SMS ID being the first column in the query output), highlight the machines, and paste them into a Notepad file.

output_directory

The directory where the delete-MIF file is written. The default is the LastLogonServerPath and ISVMIFCollectionPoint from C:\SMS.INI. The output directory can be on any logon server in logon.srv\isvmif.box, or on the site server in site.srv\isvmif.box. (The site.srv directory gives a slightly faster response). Microsoft recommends specifying an output directory.

DELMIF Example

The following command creates a delete-MIF file for the client with the SMS ID ABC00012:

delmif ABC00012

The following command creates a delete-MIF file for the client with the SMS ID ABC00345, and writes the delete-MIF file to D:\foo:

delmif ABC00345 d:\foo\

The following command creates a delete-MIF file for each client whose SMS ID is listed in DEL.DAT:

delmif @del.dat

DELMIF with a SQL Trigger

A SQL trigger allows you to delete clients by using either the SMS Administrator or DBCLEAN.EXE, and have delete-MIF files automatically generated. These delete-MIF files will flow up the hierarchy just like any other MIF file. (These MIF files get processed by the current site before being sent up the hierarchy, which could decrease performance on the current site server.)

To invoke DELMIF with a SQL Trigger, run the following commands from ISQL/W or a Query window in Enterprise Manager. You can copy and paste these two command groups into the SQL Query window.

It is strongly recommended that you modify the EXEC line to include an output directory (for example, exec master..xp_delmif @smsid, "D:\SMS\site.srv\isvmif.box\"). You must be logged in with sa access to create extended stored procedures. See also "Limitations."

From the Master database:

sp_addextendedproc 'xp_delmif', 'delmif.dll'

From the SMS database:

create trigger delmachine

on Machines

FOR DELETE

AS

DECLARE @smsid varchar(255)

DECLARE tIDs CURSOR FOR

select SMSID0

from MachineDataHistoryTable m (index=dwMachineID_idx),

Identification_SPEC i, deleted d

where i.datakey = m.SpecificKey and

GroupKey = 1 and

m.ArchitectureKey = 5 and

m.dwMachineID = d.dwMachineID

open tIDs

FETCH NEXT

FROM tIDs

INTO @smsid

WHILE (@@fetch_status <> -1)

BEGIN

exec master..xp_delmif @smsid

FETCH NEXT

FROM tIDs

INTO @smsid

end

close tIDs

Limitations of Using DELMIF with a SQL Trigger SQL Server Running on a Standalone Server

The SQL trigger method works best when the instance of SQL Server containing the site database is on the site server or an SMS logon server. But an instance of SQL Server containing the site database on a standalone server creates a problem.

By default, SQL Server runs under the local system account, which is a special Windows NT account with full administrative access to the local computer, but no network access. Therefore, where can the program write the MIF file? (On site servers and SMS logon servers, there is a directory on the local computer to which the process can write.) There are at least two possible cures:

  • Make the computer running SQL Server an SMS logon server, or move SQL Server to an SMS logon server.
  • Have the SQL Server service run under an account that has rights to your SMS logon servers or the site server.

Performance Issue

There may be a performance problem if many machines are deleted at once.

Access to DELMIF.DLL

When using the SQL trigger, make sure the SQL Server process has access to DELMIF.DLL. This file should be placed either in the same directory as SQL Server, or somewhere in the path.


DUMPSYNC.EXE: Resync-File Cleaner

DUMPSYNC cleans resync.cfg on all SMS logon servers in a domain.

When the information in a MIF file is out of sync with the database, SMS sends a resync request to the client containing the MIF file. SMS does this by having a resync.cfg file on each SMS logon server. This file contains (among other things) an SMS ID and the time of the resync request.

When a client connects to an SMS logon server, the client checks resync.cfg for the client's sms id; if found, the client sends a complete inventory and marks the inventory file as being a resync file. (The client also keeps track of when it sent this, so on future reads of resync.cfg, the client won't resend unless the time of the request in the resync file changes.)

SMS never cleans resync.cfg, which means the file keeps growing. DUMPSYNC cleans RESYNC.CFG.

DUMPSYNC must be run from sms\site.srv\invdom.box\domain.000 for each domain that you want to clean.

Maintenance Manager copies files from site.srv\maincfg.box\invdom.box\domain.000 and site.srv\maincfg.box\invdom.box\domain.000\invencfg.box to logon.srv on the appropriate domains. However, Maintenance Manager does not delete files from the logon servers if they are removed from the site.srv directory. A simple fix for this is to delete all the files from logon.srv\invencfg.box\*.cfg on all logon servers. Maintenance Manager will put them back.

Runs On

Alpha, x86

Files Required for DUMPSYNC

DUMPSYNC.EXE

DUMPSYNC Syntax

dumpsync [days] [/Dump]

days

All clients with a resync request in RESYNC.CFG more than days days old are removed from RESYNC.CFG, and their SMSID.CFG files are deleted from site.srv\maincfg.box\invdom.box\domain.000\invencfg.box.

/Dump

Displays the content of RESYNC.CFG.


FILETOKN.EXE: File Token Generator

FILETOKN generates token information about a file (checksum, CRC [Cyclic Redundancy Check], date, time, size, and so forth), which is used to inventory a file.

Runs On

Alpha, x86

Files Required for FILETOKN

FILETOKN.EXE

FILETOKN Syntax

filetokn filename [/b offset] [/l offset] [/w offset] [/c offset length] [/r offset length] [/s] [/t] [/x]

/b offset

Gets an 8-bit token.

/c offset length

Gets a 32-bit checksum at offset for length bytes.

/l offset

Gets a 32-bit long-integer token.

/r offset length

Gets a CCITT_CRC (Consultative Committee for International Telephone and Telegraph Cyclic Redundancy Check) at offset for length bytes.

/s

Shows string tokens and offsets.

/t

Terse mode. Less output is displayed on the screen.

/w offset

Gets a 16-bit integer token.

/x

Output values are displayed in hexadecimal.

/?

Provides a usage statement.


ISMIF16.EXE and ISMIF32.EXE: Status MIF Creator

ISMIF writes a generic status MIF file from information given through a command line and/or a dialog box (ISMIF16 only).

ISMIF16 is a 16-bit application that opens a dialog box in which you can type any information not specified on the command line; items specified on the command line appear in the corresponding fields of the dialog box.

ISMIF32 is a 32-bit application that has no dialog box; any information must be specified on its command line.

Runs On

Alpha, x86

Files Required for ISMIF16

ISMIF16.DLL
ISMIF16.EXE

Files Required for ISMIF32

ISMIF32.DLL
ISMIF32.EXE

ISMIF16 Syntax

ismif16 [-f Filename] [-c Manufacturer] [-p Product] [-v Version] [-l Locale] [-n Serial_Number] [-d Description] [-s Success] [-q] [-?]

-f Filename

Specifies the name of the MIF file that will be created. A ".MIF" extension is automatically appended. The default name is SETUP.MIF.

-c, -p, -v, -l, -n, -d

Each of these options can specify a text string. Each of these options corresponds to a field in the resulting dialog box. Strings containing spaces must be surrounded by quotation marks.

-s status

0 or 1. 1 means success.

-q

Quiet mode. No output is displayed on the screen.

-?

Provides a usage statement.

ISMIF32 Syntax

ismif32 [-f Filename] [-c Manufacturer] [-p Product] [-v Version] [-l Locale] [-n Serial_Number] [-d Description] [-s Success] [-q] [-?]

-f Filename

Specifies the name of the MIF file that will be created. A ".MIF" extension is automatically appended. The default name is SETUP.MIF.

-c, -p, -v, -l, -n, -d

Each of these options can specify a text string. Strings containing spaces must be surrounded by quotation marks.

-s status

0 or 1. 1 means success.

-q

Quiet mode. No output is displayed on the screen.

-?

Provides a usage statement.

ISMIF32 Example

ismif32 -c Microsoft -p SMS -v 1.2 -d "The most effective multi-site

management system that provides integrated desktop management for

customers with medium to large Windows environments."

The preceding command creates a file in your Windows directory called SETUP.MIF that contains:

START COMPONENT
NAME = "WORKSTATION"
START GROUP NAME = "ComponentID"
ID = 1
CLASS = "DMTF|ComponentID|1.0"
START ATTRIBUTE
NAME = "Manufacturer"
ID = 1
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(64)
VALUE = "Microsoft"
END ATTRIBUTE
START ATTRIBUTE
NAME = "Product"
ID = 2
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(64)
VALUE = "SMS"
END ATTRIBUTE

START ATTRIBUTE
NAME = "Version"
ID = 3
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(64)
VALUE = "1.2"
END ATTRIBUTE
START ATTRIBUTE
NAME = "Locale"
ID = 4
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(16)
VALUE = " "
END ATTRIBUTE
START ATTRIBUTE
NAME = "Serial Number"
ID = 5
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(64)
VALUE = " "
END ATTRIBUTE
START ATTRIBUTE
NAME = "Installation"
ID = 6
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(64)
VALUE = "DateTime"
END ATTRIBUTE
END GROUP

START GROUP
NAME = "InstallStatus"
ID = 2
CLASS = "MICROSOFT|JOBSTATUS|1.0"
START ATTRIBUTE
NAME = "Status"
ID = 1
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(32)
VALUE = "Failed"
END ATTRIBUTE

START ATTRIBUTE
NAME = "Description"
ID = 2
ACCESS = READ-ONLY
STORAGE = SPECIFIC
TYPE = STRING(148)
VALUE = "The most effective multi-site management system
that provides integrated desktop management for customers with medium to large Windows environments."
END ATTRIBUTE
END GROUP
END COMPONENT


MIFNAME.EXE: MIF File Renamer

MIFNAME gives SMS 1.0 and 1.1 MIF files new file extensions based on their content.

The SMS 1.2 dataloader is multithreading for different types of MIF files. The different types are determined by different file extensions on the MIF files. However, SMS 1.0 and 1.1 make no distinction among different types of MIF files (all have a .MIF extension). Therefore, MIF files being passed up a hierarchy from a 1.0 or 1.1 site to a 1.2 site will not take advantage of the 1.2 dataloader's multithreading.

MIFNAME solves this by scanning the current directory (which should be \sms\site.srv\dataload.box\deltamif.col) and changing MIF file extensions according to their content. MIFNAME does this at intervals specified on the command line.

Runs On

Alpha, x86

Files Required for MIFNAME

MIFNAME.EXE

MIFNAME Syntax

cd \sms\site.srv\dataload.box\deltamif.col
mifname [sleep_time]

sleep_time

The number of seconds to wait between checks of the dataload.box directory. If this argument is omitted, only a single check is made. If sleep_time is -1, MIFNAME displays a list of all MIF file types and their quantity, but does not rename any. To rouse MIFNAME from sleep_time mode, press crtl + c.


NEWSVCAC.EXE New Service Account Creator

For security reasons, it is a good idea to replace your SMS service account from time to time. This utility is used to replace the service account in some or all SMS sites within a multisite hierarchy. You can initiate the update from the central site or from any primary site.

The following conditions must be met for the New Service Account utility to function properly:

  • A single user account must be used within the SMS hierarchy as the service account.
  • The service account must have Logon As Service and Local Administrator privileges on all SMS sites.
  • There must be trust relationships between all of the domains that contain the SMS sites to be updated.
  • All of the SMS sites must be using the same service account, defined as domain/username.
  • All of the sites must be directly contactable. The New Service Account utility will not update remote sites.
  • All of the sites must use the same language or code page.

The sites involved can be using more than one version of SMS. This utility can be run on any primary domain controller, backup domain controller, or server that is running either Windows NT 3.51 or Windows NT 4.0.

The New Service Account utility uses a graphical user interface (GUI). The first screen provides explanatory text.

In the top half of the second screen you must enter the domain and name of the existing service account, and the password. In the bottom half of this screen, enter the domain, name, and password for the new service account.

Use the third screen to specify which sites will have the service name changed.

In the final screen, the sites you have selected are shown. Click Update to begin updating the sites you have selected.

The utility will update 10 sites simultaneously, and will begin updating the next in the list as soon as one of those updates is completed. This process continues until all of the sites have been updated. For each site the following steps are taken:

All services on the site are shut down.

The new account is given 'Logon As Service' privilege.

The new account is added to the Local Administrators group.

The SMS Service Account is updated to use the new account.

The site is restarted.

A log of the process is added the SMS log directory, with the filename NEWSVCAC.LOG.

Runs On

x86

Files Required for NEWSVCAC

NEWSVCAC.EXE


NLSMSG*.EXE: NLS Message Maker

NLSMSG displays National Language Support (NLS) messages from logon scripts at run-time, allowing a single SMS logon server to support clients of multiple languages. NLSMSG was created to replace echo and choice with something that is language-independent and localizable.

Runs On

x86

Files Required for NLSMSG

NLSMSG16.EXE, for 16-bit systems
NLSMSG32.EXE, for 32-bit systems
NLSMSGO2.EXE, for OS/2 systems

These files can be found in
site.srv\maincfg.box\client.src\platform.bin

NLSMSG Syntax

nlsmsg message_ID [/f file_name] [/m default_message] [/c choices [/t c,nn]] [/n NT_lang_ID] [/w Win_lang_ID] [/d DOS_country_code] [/p path] [/v]

Note Usually, only message_ID, /m, /c, and /t are used. In this case, NLSMSG looks for NLSRES.INI in the directory containing NLSMSG*.EXE. NLSRES.INI specifies which resource DLL to use for the current language. That DLL is opened and the string corresponding to message_ID is retrieved and printed to the screen.

The /n, /w, and /d options override the default language. NLSMSG attempts to determine the current language setting automatically, so these options are usually not needed.

message_ID

The message ID of a National Language Support (NLS) string. message_ID refers to the string table identifier in a resource-only DLL. By default, NLSMSG uses NLS_LS.DLL from the appropriate language subdirectory; for example, x86.bin\00000409\NLS_LS.DLL.

/f file_name

Specifies a DLL file to search for the message specified by message_ID. This option allows a different DLL to be used instead of the default: NLS_LS.DLL, which might be useful if you want to make your own language-independent scripts.

/m default_message

Specifies a message to use if there's an error finding the message specified by message_ID.

/c choices

Specifies allowable user-response keys, such as Y or N. (This option behaves identically to /c for the choice command.)

/t c,nn

Specifies a default choice, c, after nn seconds with no user response. (This option behaves identically to /t for the choice command.)

/n NT_lang_ID

Specifies a Windows NT language ID to use; for example, U.S. English is 0x0409.

/w Win_lang_ID

Specifies a Windows language ID to use; for example, U.S. English is ENU.

/d DOS_country_code

Specifies a DOS country code to use; for example, USA is 1.

/p path

Specifies a path to NLS files that overrides the default location, which is the same directory as the one containing NLSMSG.EXE.

/v

Verbose mode. More output is displayed on the screen.

/?

Provides a usage statement.


PDFWIZ.EXE: PDF Wizard

PDFWIZ is a package definition file (PDF) wizard. Use PDFWIZ to make an application easier to distribute and install with SMS. Starting PDFWIZ opens a window on your console with directions for its use.

The window prompts for package information, supported platforms, whether to inventory, and so forth, and generates a PDF that can be loaded into SMS. PDFWIZ does not depend on any SMS DLLs, so PDFWIZ can run on any computer running Windows.

If the SMS Admin user interface is installed, you may prefer to use SMS Admin to create the package, and then extract the package from the database using WRITEPDF.EXE.

Runs On

Alpha, x86

Files Required for PDFWIZ

PDFILE.DLL

PDFWIZ.EXE

PDFWIZ Syntax

pdfwiz


PGCSET32.EXE: PGC Status Setter

PGCSET32 sets the PGC status in a batch file under Windows NT or Windows 95. PGCSET32 sets the following registry key:

HKEY_CLASSES_ROOT
\SMS
\APPLICATIONS
\regname
\CONFIGURATION
\STATUS=status

PGCSET32 sets the DOS ERRORLEVEL to one of the following values:
0 = Success
1 = Wrong number of arguments
2 = Unused (used only by 16-bit version)
3 = Cannot create or open the Registry key
4 = Cannot set the value of the Registry key

Runs On

Alpha, x86

Files Required for PGCSET32

PGCSET32.EXE

PGCSET32 Syntax

pgcset32 program_item_registry status

program_item_registry

Specifies the name used in the application's package definition file for the application's program item.

status

Specifies the status of the configuration as SUCCESS or FAIL.

/?

Provides a usage statement.


RSAPPCTL.EXE: Shared Applications Database Resetter

When run on a site server, RSAPPCTL resets the shared applications databases (SADs) of child sites. The SADs are cleared and the shared application information is re-sent from the site server running RSAPPCTL.

Running RSAPPCTL causes the SAD to regenerate itself. The SAD for this site and/or its child sites can be reset.

Runs On

Alpha, x86

Files Required for RSAPPCTL

RSAPPCTL.EXE

RSAPPCTL Syntax

rsappctl {/self | /all | /site:site_code | /siteserver:server}

/self

Resets the shared applications database (SAD) for the site server running RSAPPCTL, but not its child sites.

/all

Resets the SADs for all child sites, but not the site server running RSAPPCTL.

/site:site_code

Resets the SAD for the child site specified by site_code.

/siteserver:server

Resets the SAD for the site server specified by server. Use this option if RSAPPCTL is running on a site other than the one specified by server.

/?

Provides a usage statement.


SETCLCFG.EXE: Client Configuration Setter

SETCLCFG forces a client to install the Client Configuration Services, or gets or sets values in the Client Services portion of a client's registry.

Runs On

Alpha, x86

Files Required for SETCLCFG

SETCLCFG.EXE

SETCLCFG Syntax

setclcfg client {/c | /r} component [state]
setclcfg client /f logon_server request_ID
setclcfg client /p parameter [value]
setclcfg client /u remote_computer

Note For any computer name, an asterisk (*) specifies the computer running SETCLCFG.

client

The client to act on.

/c

Displays the Current Installation State of component, or sets component's Current Installation State to state.

/r

Displays the Requested Installation State of component, or sets component's Requested Installation State to state.

component

"Remote Control", "Client Inventory", or "SNMP Trap Translator", and must be typed with quotes.

state

"Installed", "Not Installed", "Started", or "Disabled", and must be typed with quotes.

/f logon_server request_ID

Creates a Client Configuration Request (CCR) on logon_server. The CCR is named request_ID. An asterisk (*) for request_ID causes the request ID to be site_code00001.CCR; for example APE00001.CCR.

/p parameter [value]

Displays the value of parameter, or sets parameter to value. parameter is a ClientServices parameter, such as ClientArchitecture, or Language ID. If the parameter contains spaces, enclose it in quotes (for example, "Log Directory".)

/u remote_computer

Unlocks an access token on remote_computer.

/?

Provides a usage statement.


SETGUG.EXE: Global User Group Setter

SETGUG sets the Global User Group (GUG) reporting interval by using a PCM job. This is useful for reducing the number of User Group enumerations performed in a complex trust model.

Runs On

Alpha, x86

Files Required for SETGUG

SETGUG.EXE

SETGUG Syntax

setgug [/e {on | off}] [/i days]

/e

Specifies whether Global User Group enumeration is on or off for this site

/i

Specifies the number of days between enumeration cycles. The minimum is 1.


SKIPINV.EXE: Inventory Skipper

SKIPINV is a small program that can be used to determine whether or not an SMS client needs to do an inventory scan. Normally, before an SMS client can determine if inventory should be taken, it must transfer several large programs across the network from the logon server, and then it must load these programs into local memory. These programs are used to scan for inventory and to verify the client setup; together, they require about 1 MB of disk space. SKIPINV lets clients quickly determine whether inventory should be taken. If SKIPINV indicates that inventory is not needed, then the client can load fewer programs, and the load on the SMS logon servers can be reduced.

When called from a batch file, SKIPINV will return one of the following values:

Return value | Description
0 | Inventory scan not needed.
1 | Software inventory scan needed.
2 | Hardware inventory scan needed.
11 | Error: C:\SMS.INI could not be found.
12 | Error: SMS.INI file was found but was invalid or could not be read.

To avoid loading the inventory programs when inventory is not needed, SKIPINV should be inserted into the SMS batch file that clients run to configure SMS (SMSLS.BAT or RUNSMS.BAT). The batch file should use the return code from SKIPINV to determine whether inventory should be run. See the example below for further details.

Runs On

All supported platforms and operating systems (except for Macintosh).

Files Required

SKIPINV.EXE

Syntax

SKIPINV.EXE

Using SKIPINV

If you want to use SKIPINV to skip unneeded inventory scans on all computers, you should place the call to SKIPINV in the SMSLS.BAT or the RUNSMS.BAT file on all SMS logon servers. The batch file should check the return code from SKIPINV to determine whether the program worked, and whether any inventory scans are required. It should check all possible return values, checking the highest values first (since this is how they are processed in the batch file).

The call to SKIPINV should be inserted before one or both of the calls to SETLS. For each supported operating system, there are two calls to SETLS; the first calls the Client Setup code, the second calls the Inventory Agent. You can use SKIPINV to skip all calls to SETLS, or you can skip only the call to the Inventory Agent.

Caution There are issues associated with skipping the Inventory Agent or the Client Setup code. The Inventory Agent performs many functions, including inventory scans, resyncs, and site or domain moves. The Client Setup code performs component installation, removal, and upgrades, as well as other functions. Therefore, if you use SKIPINV, some or all of these functions may not be called during the logon or RUNSMS process.

The following example shows how SKIPINV might be used in the SMSLS.BAT file. This example skips all calls to SETLS if SKIPINV determines that inventory is not needed. This example uses the existing :START and :END labels, as well as a new label called :NOSKIP. The :END label is not shown in this example because it is near the end of the existing batch file.

Note You must ensure that the SKIPINV program exists in a directory that can be accessed by the SMS clients. The following example assumes that the SKIPINV program exists in the same directory as the logon script SMSLS.BAT. It uses the %0 syntax to ensure that the SKIPINV program is run from the same directory as the batch file.

REM The following label exists in the standard SMSLS.BAT file

:START

REM The following (new) line calls the SKIPINV program using the

REM %0 syntax; this syntax tells the batch file that the program

REM being called exists in the same directory as the logon script.

%0\..\skipinv.exe

REM The following (new) lines check the return code from SKIPINV.

REM If the return code is 11 or 12, an error has occurred,

REM so we better call SETLS.

if errorlevel 12 goto NOSKIP

if errorlevel 11 goto NOSKIP

REM If the return code is 1 or 2, SKIPINV has determined

REM that an inventory scan is required, so we better call SETLS.

if errorlevel 2 goto NOSKIP

if errorlevel 1 goto NOSKIP

REM If the return code is 0, inventory is not needed,

REM so we will skip the call to SETLS.

if errorlevel 0 goto END

REM You need to add the following label to the batch file

REM immediately following the SKIPINV tests.

:NOSKIP

If you wanted to skip the call to the Inventory Agent only, you would put the SKIPINV logic after the first SETLS call (to the Client Setup code), but before the second SETLS call (to the Inventory Agent). For Windows NT computers, the call to SKIPINV (and the return code tests) would go between these two lines:

setls%SMS_OS% -m:E -i -p:%SMS_BIN%\CLI_NT.EXE -pa:/p:%%SMS_UNC%%\ -pa:%SMS_VERBOSE% %SMS_VERBOSE%

%0\..\skipinv.exe

REM If SKIPINV returns an 11 or a 12, client setup had problems,

REM so we should clean up and quit.

if errorlevel 12 goto RESTORE

if errorlevel 11 goto RESTORE

REM If SKIPINV returns a 2 or a 1, an inventory scan is required.

if errorlevel 2 goto SCAN

if errorlevel 1 goto SCAN

REM If SKIPINV returns a 0, everything is OK and no scan is needed.

if errorlevel 0 goto RESTORE

:SCAN

setls%SMS_OS% -m:E -i -p:%SMS_BIN%\INVWIN32.EXE -pa:/l:%%SMS_UNC%%\ -pa:/e -pa:/t0 -pa:/i -pa:%SMS_VERBOSE% %SMS_VERBOSE%


SMSMAINT.SQL: Database Maintainer

SMSMAINT removes unused data from an SMS database and performs other tasks to keep the SMS database working well.

Runs On

Alpha, x86

Files Required for SMSMAINT

SMSMAINT.SQL

SMSMAINT Syntax

To run SMSMAINT.sql, open it in an ISQL/w command window and execute it.

Additional directions are in the smsMAINT.sql file.


SQLPWD.EXE: SQL Password Changer

SQLPWD changes the SQL Server account and/or password used by the SMS services. SQLPWD prompts for the SQL Server name, the account username, and the current and new passwords.

Runs On

Alpha, x86

Files Required for SQLPWD

SQLPWD.EXE

SQLPWD Syntax

sqlpwd


UGMIF.EXE: User Group MIF Creator

UGMIF creates global user group Management Information Format (MIF) files for trusted domains. These MIF files contain either the user groups detected in the domain or, depending on the options used, the differences between what is detected and what exists in the SMS database.

In either case, the MIF files are written by default to the site's SMS Inventory Data Loader in-box, which means the SMS database will be updated automatically with the latest user group information.

Runs On

Alpha, x86

Files Required for UGMIF

UGMIF.EXE
SMSAPI.DLL
OBJECTTY.DLL

SMSAPI.DLL and OBJECTTY.DLL from the BackOffice SDK must be in the UGMIF's path. These files are not shipped with the SMS Resource Kit.

UGMIF Syntax

ugmif [/t] [/v] [/d:domain] [/m:MIF_directory] [/s:site_code] [/u[:SQL_Server[:database[:SQL_account[:SQL_password]]]]]

/d:domain

Specifies a Windows NT domain. User groups will be listed from this domain and all trusted domains of this domain if /t is also used.

/m:MIF_directory

A directory path where the user group binary MIF file will be written. If /m is not specified, the binary MIF file is written to the site's SMS Inventory Data Loader in-box.

/s:site_code

Specifies the site code to use when writing the MIF files. The default is the site code of the site containing the computer running UGMIF.

/t

Includes trusted domains.

/u

Updates an SMS database with MIF files that reflect the difference between the user groups found in the domain and the user groups in the SMS database.

:SQL_Server

The computer running SQL Server containing the SMS database. The default is the site server.

:database

The SMS database. The default is the site database.

:SQL_account

The account to use to access inventory. The default is the SMS SQL Server account.

:SQL_password

The password to SQL_account. UGMIF prompts if this is not specified.

/v

Verbose mode. More output is displayed on the screen.

/?

Provides a usage statement.


WRITEPDF.EXE: PDF Writer

Given a package ID, WRITEPDF writes a PDF (Package Definition File) from the information about that package in the database.

Note If you want the system to reboot after installing the software described in the PDF, you must manually edit the PDF created by WRITEPDF: change the line

synchronousExitRequired=False

to

synchronousExitRequired=True

Runs On

Alpha, x86

Files Required for WRITEPDF

WRITEPDF.EXE

WRITEPDF Syntax

writepdf server account password database package_ID

server

The computer running the instance of SQL Server containing database.

account

The account to use when accessing database.

password

The password for account. If the password is blank or contains spaces, it must have quotation marks around it; for example, "Harry Browne".

database

The name of the database containing the package information.

package_ID

The package ID for which to write a PDF.

/?

Provides a usage statement.


WRITEQDF.EXE: QDF Writer and Reader

Given a query ID, WRITEQDF either writes a Query Definition File (QDF) from the information about a query in the database, or reads a specified QDF into SMS, where it can be manipulated in the SMS Administrator's Query window.

Runs On

Alpha, x86

Files Required for WRITEQDF

WRITEQDF.EXE

WRITEQDF Syntax

writeqdf server account password database {QDF | query_ID}
[/import | /export]

server

The computer running the instance of SQL Server containing database.

account

The account to use when accessing database.

password

The password for account. If the password is blank or contains spaces, it must have quotation marks around it; for example, "Harry Browne".

database

The name of the database containing the query information.

QDF

A Query Definition File (QDF) to read into SMS.

query_ID

A query ID for which to write a QDF.

/import

Specifies that a QDF is being read.

/export

Specifies that a QDF is being written. This is the default behavior.

/?

Provides a usage statement.


ZAP.EXE: File Zapper

ZAP deletes a file that is in use, or which cannot otherwise be deleted. The file is marked for deletion, and is actually deleted when the computer is rebooted.

Runs On

Alpha, x86

Files Required for ZAP

ZAP.EXE

ZAP Syntax

zap file_name

file_name

The file to be deleted.


Troubleshooting Tools


BUGDATA.EXE: Bug Data Collector

BUGDATA collects the SMS Registry, log files, and site control image, and puts them in a compressed file for subsequent analysis. HDECOMP.EXE can decompress the file.

Runs On

Alpha, x86

Files Required for BUGDATA

BUGDATA.EXE

BUGDATA Syntax

bugdata [\\server] [output_file]

server

The computer name of the SMS site server from which data will be gathered. The default is the local computer.

output_file

The name of the compressed output file to be written. The default is BUGDATA.SMS.


DUMPSEND.EXE: Display Send Request

DUMPSEND displays the contents of a send request file, which comprises these records:

Send request data | Destination site, priority, job name, job ID, and out-box location
Cancel | Specifies whether this send request is canceled
Action code | Specifies whether this send request is retrying or deleted
Address (multiple records allowed) | Encrypted names, as well as gateway and destination addresses
Package file | The name of the package file
Instruction file | The name of the instruction file
Sender | Information about the sender's history: status, time of last event, start time, number of times a sender took this send request, and the size of this send request
Access | File access information
SSPS | Information about the remote site installation

Runs On

Alpha, x86

Files Required for DUMPSEND

DUMPSEND.EXE

DUMPSEND Syntax

dumpsend [/p] filename

/p

Pause before DUMPSEND exits. If you run DUMPSEND in a command prompt window that closes after the command is finished, using /p allows you to see DUMPSEND's output before the window closes. Then press any key to close the command prompt window.

filename

The name of the send request file whose contents you wish to display.


ERROR32.EXE: Error Code to Message

ERROR32 displays the text of a message for the specified Windows NT (Win32 subsystem, driver, or service) error code. If no application or event-log message DLL is specified, the message text comes from the system message table.

Runs On

Alpha, x86

Files Required for ERROR32

ERROR32.EXE

ERROR32 Syntax

error32 code [:code] [source_name | message_DLL] [insertion_string[...]] [*]

code

Specifies an error code (in decimal) for a Windows NT error, or an event code for an application or system source (such as SMS). The error code is assumed to be a Win32 error unless source_name or message_DLL is specified.

:code

Specify another code to form a range; for example, 3:11 specifies the codes from 3 to 11, inclusive.

source_name

Specifies an application (such as SMS) or system name registered for the Windows NT Event Log. Cannot be used with message_DLL.

message_DLL

Specifies a full or partial path to a Windows NT event_log message DLL file (such as NETMSG.DLL). Cannot be used with source_name.

insertion_string

Specifies one or more strings to be inserted into the displayed message.

*

Displays messages for all matching languages and severities.

ERROR32 Example

The following command returns the message text from the system message table for error code 2:

error32 2

The system cannot find the file specified.


FILEMOVE.EXE: File Mover

File Mover allows you to automatically move or copy files from a selected source directory to a specified destination directory. It actually consists of two utilities: FILEMOVE.EXE and FMUI.EXE.

Caution SMS uses files to schedule tasks and other events. Moving these files with File Mover may interfere with the proper operation of SMS.

FILEMOVE.EXE runs on the target system (the computer that you want to monitor) and periodically configures itself according to the values in the local system's registry. It monitors files in the specified source directory, either by polling the directory at set intervals or by using Windows NT Directory Change events. When the specified files are found, it moves or copies the files to the destination directory. FILEMOVE.EXE writes its status to its log file (FILEMOVE.LOG). When this log file reaches its maximum size, it is closed and renamed FILEMOVE.LO_. A new FILEMOVE.LOG file is then created.

FMUI.EXE is the utility that you use to get and set the registry values that configure FILEMOVE.EXE. (These registry values are located in HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\SMS_FILE_MOVER). FMUI.EXE can run on any computer that has local or network access to the registry of the computer that is running FILEMOVE.

The following values are set with the FMUI utility (these are the values in the FMUI utility itself, not in the registry):

Computer Name

The name of the target computer running FILEMOVE.

File Mask to Scan

The filter that FILEMOVE should use to select the files to be moved or copied. Defaults to all files (*.*) if no mask is specified.

Source Directory to Monitor

The directory from which to move or copy files. FILEMOVE will not work if this directory is not specified or if the specified directory does not exist.

Destination Directory

The directory to which to move or copy files. FILEMOVE will not work if this directory is not specified or if the specified directory does not exist.

Log File location

The full path to the FILEMOVE log file. Defaults to C:\.

File size in Kbytes

The size of the FILEMOVE log file, specified in kilobytes. Defaults to 128K.

Wait for Directory Change Event

Selecting the checkbox specifies that FILEMOVE should use Windows NT Directory Change notification to monitor files. Clearing the checkbox specifies that FILEMOVE should use polling.

Poll Source Directory every nn seconds

nn specifies the default polling interval for FILEMOVE. It is only valid if polling has been specified.

Delete files after copying

Selecting the checkbox specifies that FILEMOVE should move the files to the destination directory (and delete the source files). Clearing the checkbox specifies that FILEMOVE should simply copy the files (and leave the source files intact).

Overwrite duplicate filenames

Selecting the checkbox specifies that FILEMOVE should overwrite duplicate files in the destination directory. Clearing the checkbox specifies that FILEMOVE should change duplicate filenames so that no files are lost. If FILEMOVE changes any file names, the change is written to the FILEMOVE log file.

Runs On

x86

Files Required

FILEMOVE.EXE, FMUI.EXE, FMUI.HLP, FMUI.CNT, FMUI.FTS

FILEMOVE Syntax

FILEMOVE can be run as an executable or as a service. In both cases, it requires Administrator rights on the computer to be monitored. It will also need rights to the source directory, the destination directory, and the local registry. When run as a service, it will also need the right to "Log On As A Service".

To start FILEMOVE as an executable

FILEMOVE /E

Note You can type "Start FILEMOVE /E" to run FILEMOVE in a separate command window. This also allows you to end FILEMOVE by closing its command window.

To install FILEMOVE as a service (using SVCCTRL.EXE)

Create a domain user account that has the Log on as a Service right. Put the account in the Domain Admins group.

At a command prompt, change to the directory containing SVCCTRL.EXE, and type svcctrl.

At the prompt, type 1, for Install.

Type the name of the FILEMOVE service (SMS_FILE_MOVER):

Enter service name: SMS_FILE_MOVER

Type that name of the account you created in Step 1:

Enter account name [domain\user]: RAYDOMAIN\RAYMCC

Type the account's password, which is case-sensitive:

Enter password: ItsaSecret

Type the name of the computer to install the service on:

Enter machine name [add \\]: \\RAYMACHINE

Type the path of the service on the local machine. Include the executable file:

Enter path: C:\BIN\FILEMOVE.EXE

Specify whether the service is to be started automatically when the computer is restarted:

Autostart service during bootup? (Y/N): N

When SVCCTRL.EXE indicates that the service has been installed, type 0 to exit SVCCTRL.EXE.

After the service has been installed, the service can be controlled with SVCCTRL.EXE or with Service Manager.

FMUI Syntax

FMUI

Note The user running FMUI:EXE needs rights to monitor the registry on the computer running FILEMOVE.EXE.


FIPERF.BAT: Add File Counters to Performance Monitor

FIPERF adds counters to Performance Monitor that monitor the number, size, and age of files in various directories. This ability is particularly useful in SMS to monitor directories such as SMS\site.srv\dataload.box\deltamif.col.

The name of the new Performance Monitor object is SMS_Files. Look at the Explain text in Performance Monitor for definitions of the counters.

FIPERF must be run on the computer running the SMS site services.

Usage Notes

  • Do not run these counters with too small a polling interval, which adversely affects server performance because the server continuously scans directories. A reasonable minimum polling interval is one minute, but one hour is recommended.
  • The directories that are monitored are stored in the registry in \\HKEY_LOCAL_MACHINE\SYSTEM\CURRENTCONTROLSET\SMS_FILES\LINKAGE. Add or remove items from this list if you wish (see next note).
  • Due to the nature of Performance Monitor, whenever you bring up a list of counters, the counter DLLs are called to return data. This means that a scan of all the directories is performed. If these directories have many files, this could take from a few seconds to a few minutes. If you find that there is a large delay and that there are directories that you don't want to monitor, remove them from the Linkage key.

Removing FIPERF

To remove this software, run the following command (unlodctr is provided with Windows NT):

unlodctr SMS_Files

Do not simply delete the registry keys; you could lose other Performance Monitor counters.

Runs On

Alpha, x86

Files Required for FIPERF

FIPERF.DLL
SMSPERF.DLL

The following files are required for installing the SMS_Files counter, but can be removed after installation:

FIPERF.BAT
FICTRNM.H
FI.INI

FIPERF Syntax

fiperf path

path

The path to the root SMS directory; for example, D:\SMS.


HCOMP.EXE: Package File Compressor

HCOMP compresses an SMS package file (.PKG) using the same compression algorithm used when SMS creates a package in SMS Administrator.

HDECOMP decompresses files compressed by HCOMP.

HVALCOMP validates files compressed by HCOMP.

Note HCOMP, HDECOMP, and HVALCOMP require access to the files SMSZIP.DLL and SMSUNZIP.DLL, which reside in the \site.srv\platform.bin directory. Therefore these commands must be run from that directory, or the directory must be included in the path.

Runs On

Alpha, x86

Files Required for HCOMP

HCOMP.EXE
SMSZIP.DLL

HCOMP Syntax

hcomp source destination

source

An SMS package file (.PKG) to be compressed.

destination

The name to give to the compressed SMS package file.

/?

Provides a usage statement.


HDECOMP.EXE: Package File Decompressor

HDECOMP decompresses an SMS package file (.PKG).

Note HDECOMP requires access to the file SMSUNZIP.DLL, which resides in the \site.srv\platform.bin directory. Therefore, this command must be run from that directory, or the directory must be included in the path.

Runs On

Alpha, x86

Files Required for HDECOMP

HDECOMP.EXE
SMSUNZIP.DLL

HDECOMP Syntax

hdecomp source destination

source

The SMS package file to decompress.

destination

The directory in which the decompressed files are to be placed.

Both source and destination must be explicitly specified.

For a usage message, run the command with no arguments (/? Is not accepted).


HVALCOMP.EXE: Compressed Package File Validator

HVALCOMP validates a compressed package file (.PKG).

Note HVALCOMP requires access to the files SMSZIP.DLL and SMSUNZIP.DLL, which reside in the \site.srv\platform.bin directory. Therefore, this command must be run from that directory, or the directory must be included in the path.

Runs On

Alpha, x86

Files Required for HVALCOMP

HVALCOMP.EXE
SMSZIP.DLL
SMSUNZIP.DLL

HVALCOMP Syntax

hvalcomp source

source

The SMS package file to validate.

Run with no arguments for a usage message (/? Is not accepted).


MIFCHECK.EXE: MIF Checker

MIFCHECK is an MIF parser and syntax checker that verifies text MIF files before submitting them to an SMS system. MIFCHECK reports syntax and semantic errors, and is designed to help ISVs writing MIF files for new components for the Inventory Agent to report.

Runs On

Alpha, x86

Files Required for MIFCHECK

MIFCHECK.EXE

MIFCHECK Syntax

mifcheck [/dump] file

/dump

Dumps the parsed information to the console. If MIFCHECK is run without the /dump option, the MIF files are checked for syntax errors.

file

A MIF text file.

/?

Provides a usage statement.


MIPERF.BAT: Add MIF File Counters to Performance Monitor

MIPERF adds a new set of counters to Performance Monitor. These counters monitor the number of MIF files being processed by the dataloader.

The name of the new Performance Monitor object is SMS_MIFS. Look at the Explain text in Performance Monitor for a definition of the counters.

MIPERF must be run on the computer running the SMS site services.

Usage Notes

  • The New Mifs counter can only be displayed using the Performance Monitor in Windows NT 4.0 or later. Total Mifs works with any Performance Monitor.
  • The Total Mifs number is stored once per server, which means that when you first open a counter for Total Mifs, it starts at 0 and counts up. If you start a second instance of Performance Monitor, it starts with the number that was last shown in the first instance of Performance Monitor. If you close all instances of Performance Monitor, then start the Total Mifs counter again, it starts from 0 again.
  • The counters work by reading the log file, so if you turn off tracing for the dataloader, the counters no longer work.
  • Some MIF files (such as usergroup MIF files) contain multiple "MIF files" per file; that is, If you have 100 user groups, the dataloader reports 100 machines processed while it processes this MIF file. The counter then shows this as 100 MIF files processed.
  • Despite these limitations, this counter presents a reasonable view of the performance of the dataloader if used over a period of days.

Removing MIPERF

To remove this software, run the following command (unlodctr is provided with Windows NT):

unlodctr SMS_Mifs

Do not simply delete the registry keys; you could lose other Performance Monitor counters.

Runs On

Alpha, x86

Files Required for MIPERF

MIPERF.DLL
SMSPERF.DLL

The following files are required for installing the SMS_MIFS counter, but can be removed after installation:

MIPERF.BAT
MICTRNM.H
MI.INI

MIPERF Syntax

miperf


NADRESET.BAT: NAD Resetter

SMS network applications, packages, and program groups are listed in a network applications database (NAD). The NAD is replicated from the parent site to child sites. If a child site is detached from a parent site, it retains the parent site's NAD; this prevents a large-scale deletion of program groups and program items from the clients that may still have access to these items.

When you no longer need the program groups and program items from the former parent site, remove them by running NADRESET.BAT. This utility will create a directory named 10000000.NAD in SMSROOT\SITE.SRV\SITECFG.BOX, and then create the following files in that directory:

TRANSLOG.CLR
ALL.RST

Once this is done, the Applications Manager will remove any NAD items that were not created locally. This will be done in the next polling period of Applications Manager; generally the local site and logon servers will be updated within five to six minutes. Then the 10000000.NAD directory and the files it contains are deleted by the Applications Manager.

Runs On

x86

Files Required for NADRESET

NADRESET.BAT

NADRESET Syntax

nadreset smsroot

smsroot

The drive letter and directory where SMS is installed; for example, D:\SMS.

/?

Provides a usage statement.


NADUSER.EXE: NAD User

NADUSER is a Win16 application that, when run on a client, can indicate:

  • User global group membership
  • Network application database (NAD) applications available to a user based on the user's global group membership

Runs On

x86

Files Required for NADUSER

NADUSER.EXE
NADAPI.DLL
SMSNET.DLL

This tool must be run from the directory in which the DLLs are located: SMS\SITE.SRV\platform.BIN.

NADUSER Syntax

naduser


PCMDUMP.EXE: PCM Dumper

When run on a site server, PCMDUMP dumps the contents of a Package Command Manager instruction file.

Runs On

Alpha, x86

Files Required for PCMDUMP

PCMDUMP.EXE
advapi32.dll
gdi32.dll
kernel32.dll
user32.dll
winspool.drv

PCMDUMP Syntax

pcmdump [options] {/a | /r instruction_file}

/a

Dumps all files in the instruction box (SMS\logon.srv\pcmins.box).

/d

Dumps detailed information.

/l

Lists the contents of the PCM instruction box (SMS\logon.srv\pcmins.box).

/p

Pauses before PCMDUMP exits. If you run PCMDUMP in a command prompt window that closes after the command is finished, using /p allows you to see PCMDUMP's output before the window closes. Then press any key to close the command prompt window.

/r instruction_file

Dumps a Package Command Manager instruction file (*.INS). from the instruction box (SMS\logon.srv\pcmins.box).

/?

Provides a usage statement.

PCMDUMP Output

PCMDUMP writes the contents of one or more PCM instruction files to the screen. These files have the following fields:

PCM Version | The version of the PCM instruction file.
SiteID | The site code, as it appears in the SMS Administrator.
RequestID | A per-site ID used by senders.
PackageID | The package identifier, as it appears in the SMS Administrator's Packages window.
JobID | The job identifier, as it appears in the SMS Administrator's Jobs window.
Install Flag | Either No network speed check required, which means the package is installed regardless of the speed of the network connection, or Fast network required, which means the package is installed only if the network connection meets the requirement for a fast network (see the SMS Administrator's Guide).
Install By Date | The date and time by which the package must be installed.
Install By Full | Yes or No. Controls whether the previous record is used.
Display Date | The date and time that PCM is displayed on clients' screens.
Display Full | Yes or No. Controls whether the previous record is used.
Expiration Date | The date and time the package expires; the job cannot be executed after this time.
Expiration Full | Yes or No. Controls whether the previous record is used.
User Input Flags | Nothing, or one or more of the following: User Input Required, System (Background) Task, and Synchronous System Exit Required, which means that the job will restart the computer upon completion of the job.
Operating System | The operating systems on which the job will run.
Disk Usage | Reserved.
Run Command | The executable file name.
WCL Name | Workstation Command Line, a descriptive name for the command and its effect.
Server(s) | A list of package servers and paths containing all the files needed to run the command. Might include Zone, which specifies an Apple network zone.
Package Name | Same as in the SMS Administrator's Package Properties window.
Comments | Same as in the SMS Administrator's Package Properties window.
Domain Name | Unused.
Reserved | Unused.


RAWCHECK.EXE: RAW Checker

RAWCHECK determines whether a RAW file created by a client is valid.

Runs On

Alpha, x86

Files Required for RAWCHECK

RAWCHECK.EXE

RAWCHECK Syntax

rawcheck filename [/v]

filename

A RAW file to be validated.

/v

Verbose mode. More output is displayed on the screen.


SENDCODE.EXE: Send Code

SENDCODE sends a numeric code to an SMS service, causing it to perform a specific task. The following table correlates the codes with the applicable SMS services and tasks.

Code | Services | Task
128 | SMS_EXECUTIVE SMS_HIERARCHY_MANAGER SMS_SITE_CONFIG_MANAGER | Starts memory allocation tracking
129 | SMS_EXECUTIVE SMS_HIERARCHY_MANAGER SMS_SITE_CONFIG_MANAGER | Stops memory allocation tracking
130 | SMS_EXECUTIVE SMS_HIERARCHY_MANAGER SMS_SITE_CONFIG_MANAGER | Dumps memory allocation data to files C:\ALERTER.MEM, APPMGR.MEM, HMAN.MEM, SCMANMEM.LOG, SCHED.MEM, SMSEXEC.MEM
131 | SMS_EXECUTIVE | Dumps the SQL cache for the SMS_EXECUTIVE service and lists the status for each SQL connection in C:\SQLCACHE.LOG
132 | All SMS services | Toggles the net pause support for an SMS service
133 | SMS_EXECUTIVE | Rereads the registry and resets the SMS tracing (logging) settings for location and size
192 | SMS_SITE_CONFIG_MANAGER | Does a watchdog cycle (verifies the current installation, checks for new logon servers, restarts any stopped components, etc.)
193 | SMS_SITE_CONFIG_MANAGER | Does a watchdog cycle and writes a status file (.CT2)
194 | SMS_SITE_CONFIG_MANAGER | Does a watchdog cycle as if an upgrade were happening (this should be preceded by a SENDCODE 234 to be most effective)
195 | SMS_SITE_CONFIG_MANAGER | Does a watchdog cycle and writes a user group MIF
196 | SMS_SITE_CONFIG_MANAGER | Does a watchdog cycle and modifies logon scripts (only if Automatically Configure Logon Scripts and Use All Detected Servers are enabled)
234 | SMS_SITE_CONFIG_MANAGER | Stops and de-installs services at this site (on the site server and all logon and helper servers)
235 | SMS_SITE_CONFIG_MANAGER | De-installs the site (de-installs all components and removes files and shares from the site server and all logon and helper servers)

Runs On

Alpha, x86

Files Required for SENDCODE

SENDCODE.EXE

SENDCODE Syntax

sendcode SMS_service code

SENDCODE Example

To trigger a watchdog cycle in SMS_SITE_CONFIG_MANAGER:

sendcode SMS_SITE_CONFIG_MANAGER 192


SMSTRACE.EXE: SMS Log File Viewer

SMSTRACE is a GUI application that views SMS log files and gets real-time updates as lines are appended to the log files.

SMSTRACE works only with the SMS 1.2 final release, not earlier versions, because of DLL incompatibility.

You can use SMSTRACE.ATD with SMSADDIN to add SMSTRACE to the SMS Administrator's Tools menu.

Runs On

Alpha, x86

Files Required for SMSTRACE

base.dll
smsapi.dll
SMSTRACE.EXE
SMSMFC.DLL

This tool must be run from the directory in which the DLLs are located: SMS\SITE.SRV\platform.BIN.

SMSTRACE Syntax

smstrace


TRACER.EXE: Text File Viewer

TRACER reads, in real time, changes made to a text file.

Runs On

Alpha, x86

Files Required for TRACER

TRACER.EXE
MSVCRT20.DLL

The file MSVCRT20.DLL is included with Windows NT 3.51, but not with Windows NT 4.0. You can copy the file from the smssetup\platform directory of the Back Office Resource Kit CD-ROM.

TRACER Syntax

tracer log_file

log_file

The file to read.


VIEWNAD.EXE: NAD Viewer

VIEWNAD runs on a client. It displays a list of shared applications that are available for a particular site. VIEWNAD also displays the server location of any listed application, and to which user groups the application is assigned.

Runs On

Alpha, x86

Files Required for VIEWNAD

VIEWNAD.EXE

VIEWNAD Syntax

viewnad


Windows NT-based Tools


SVCCTRL.EXE: Service Manager

SVCCTRL allows you to install or control local or remote services running on remote and local computers. (SVCCTRL was previously called INSTSRV. It has been renamed to avoid confusion with INSTSVC in the Microsoft Windows NT Resource Kit.)

After starting SVCCTRL, you are presented with a menu of choices; pick one:

0 | Quit | Quit the Service Manager utility.
1 | Install | Install a service. Specify a service name (it need not match the executable name), a domain and user name, a target computer name, a local path that includes the executable name, and where you want the service to autostart (start when the computer is turned on).
2 | Deinstall | Remove a service.
3 | Start | Start a service that is already installed.
4 | Start with args | Start a service with arguments.
5 | Stop | Stop a service.
6 | Pause | Pause a service.
7 | Continue | Continue a service that is paused.
8 | Query | Get the status of an installed service.
9 | Send code | Send a control code to the service. These codes are the same as those used by Send Code.
10 | Change account and password | Change the account and password information for a service. The account must have the Logon as a Service user right and belong to the Domain Admins group.
11 | Install with dependencies | The service requires that another group or service is already running.

Runs On

Alpha, x86

Files Required for SVCCTRL

SVCCTRL.EXE

SVCCTRL Syntax

svcctrl

SVCCTRL Example

To install and start the SMS_PROGRAM_COMMAND_MANAGER_NT service on a Windows NT server:

Create a domain user account that has the Log on as a Service right. Put the account in the Domain Admins group.

At a command prompt, change to a Windows NT directory containing SVCCTRL.EXE, and type svcctrl.

At the prompt, type 1, for Install.

Type the name of the service you wish to start:

Enter service name: SMS_PROGRAM_COMMAND_MANAGER_NT

Type that name of the account you created in Step 1:

Enter account name [domain\user]: RAYDOMAIN\RAYMCC

Type the account's password, which is case-sensitive:

Enter password: ItsaSecret

Type the name of the computer to install the service on:

Enter machine name [add \\]: \\RAYMACHINE

Type the path of the service on the local machine. Include the executable file:

Enter path: C:\LOGON.SRV\X86.BIN\PCMSVR32.EXE

Specify whether the service is to be started automatically when the computer is restarted:

Autostart service during bootup? (Y/N): N


KILL.EXE: Task Killer

KILL kills the application specified by a process ID, which can be gotten from TLIST.

Runs On

Alpha, x86

Files Required for KILL

KILL.EXE

KILL Syntax

kill [-f] {process_ID | pattern}

-f

Forces the process to die.

process_ID

The process ID of the task to be killed. Use TLIST to get a valid process ID.

pattern

A complete task name, or a regular expression pattern that matches a task name. KILL compares the pattern to task names and window titles.


REGLIST.EXE: Registry List

REGLIST lists the contents of the registry. Command options can limit which portions of the registry are listed.

Runs On

Alpha, x86

Files Required for REGLIST

REGLIST.EXE

REGLIST Syntax

reglist [/h:reg_hkey] [/r:reg_key_path]

/h:reg_hkey

Specifies one of the following HKEY names:

HKEY_LOCAL_MACHINE (or HKLM or MACHINE). This is the default if no name is specified with /h.

HKEY_CURRENT_USER (or HKCU or CURRENT_USER).

HKEY_USERS (or HKU or USERS).

HKEY_CLASSES_ROOT (or HKCR or CLASSES_ROOT).

/r:reg_key_path

Specifies a path to a registry key. The default is software\microsoft\sms.

/?

Provides a usage statement.


RSERVICE.EXE: Service Remote Control

RSERVICE controls a service on remote computers. The control options include:

  • Installing
  • Removing
  • Starting
  • Stopping
  • Querying
  • Pausing
  • Changing the account and password
  • Verifying the executable file
  • Sending control codes

RSERVICE operates on Win32 service programs on one or more computers running Windows NT in a single domain.

The data necessary to control a service must be specified in an initialization file. This data includes information on files and the account needed to install a service, and any arguments needed to start the service.

Runs On

Alpha, x86

Files Required for RSERVICE

RSERVICE.EXE

RSERVICE Syntax

rservice [/install] [/deinstall] [/start] [/stop] [/pause] [/continue] [/query] [/change] [/verify][/sendcode:code] [/c] [/l:log_file] [/m:computer] [/t:thread_count] [/v] [/x] init_file

/install

Installs a service on the specified computers. This includes creating a directory and copying the service's executable files to the computer, if necessary. If the service is already installed, no action is taken. If /install is used, a password is requested at run-time. If /install is used and /x is not used, the user account specified in the [service account] section of the RSERVICE initialization file is added to the Administrators local user group and granted the Log on as a Service User right on each remote computer.

/deinstall

Removes a stopped service from the specified computers. This includes deleting the service executable files and removing the directory for a computer, if necessary. If the service is not installed or is not stopped, no action is taken. If the user account specified in the [service account] section of the RSERVICE initialization file was added to the Administrators local user group on the client computer, it is removed from that local group when the /deinstall option is used and the /x option is not used.

/start

Starts a stopped service on the specified computers. If the service is already running, no action is taken. If the service is paused it will be un-paused (same as /continue).

/stop

Stops a service on the specified computers. If the service is already stopped, no action is taken.

/pause

Pauses a service on the specified computers. If the service is not running, no action is taken.

/continue

Continues (un-pauses) a service on the specified computers. If the service is not running, no action is taken.

/query

Queries the running status of the service on the specified computers. The /query command is also useful for testing the set of computers within the domain included as a result of the information in the initialization file.

/change

Allows you to change the password for the service account used by an installed service, or to change to a new service account.

Before using the RSERVICE /change command, create the new service account and password, or change the password on the existing account. If you are changing to a different service account, edit the RSERVICE initialization file to change the account specified in the [service account] section.

Then, at a time when the service is not being used, stop the service on all computers, change the password and/or service account, and restart the service. These can be done with a single command of the form:

rservice /stop /change /start initialization_file

/verify

Verifies that the executable file and the service image path have not been changed. It is recommended that you run RSERVICE with the /verify option on a regular basis, to guard against attempts to breach security by replacing a secure service. If changes have occurred, one of the following messages will be returned:

ALERT: The service registry ImagePath (bad_image_path) for service service_name on machine computer_name is incorrect!

ALERT: Executable file filename for service service_name on machine computer_name is not the correct version!

/sendcode:code

Sends a control code toa service on the specified computers. Win32 services can be written to handle user-defined control codes in the range 128 to 255.

/c

Makes an explicit connection to each computer using the service account before the service commands are executed. This option provides administrator level access to computers by using the service account specified in the initialization file instead of defaulting to the security context of the logged on user. All service commands are executed after the connection is established, and then the connection is deleted. If this option is used, RSERVICE prompts for a password.

/l:log_file

Specifies a path for an output log file. Trace-level output from RSERVICE is appended to this file.

/m:computer

Overrides [machine list] in init_file. This option causes the listed or automatically detected computers to be ignored, but all options specified in init_file are still used for computer. This option is useful for testing the information in the initialization file against a single computer before trying an operation on all computers in a domain.

/t:thread_count

Specifies the maximum number of threads that can be used (the default is 10). Specifying the number of threads gives control over the response versus the system load of RSERVICE, and affects the number of computers operated on concurrently. RSERVICE will use a separate thread for each computer and execute all of the service commands within this thread.

/v

Verbose mode. More detailed output is displayed on the screen.

/x

Used to modify the /install and /deinstall options. Prevents the user account specified in the [service account] section of the RSERVICE initialization file from being added to or removed from the Administrators local user group on the remote computer. Also prevents the service account from being granted the Log on as a service user right.

init_file

Specifies a path to an initialization file (.INI) that defines a set of computers and service parameters. The following sections are required: [domain name], [service account], [service name], [executable file].

RSERVICE Initialization File

The RSERVICE initialization file consists of sections to specify domain and computer information, service parameters, and installation parameters. The entries in all sections have this format:

Entry=parameter

[domain name]

Entries in this section specify the name of the domain containing the remote computers; RSERVICE requires that all listed computers be members of this domain. Entries in this section have the following forms:

domain_name=LISTED
domain_name=Parameter [,…]

LISTED

Specifies that the computers defined for this domain are listed in the [machine list] section; automatic detection of computers is off.

parameter [,…]

A comma-separated list of one or more of the following. Automatic detection of computers is on.

NTWD | Specifies that all computers with machine accounts in the domain are included.
NTSD | Specifies that all non-domain-controller servers with machine accounts in the domain are included.
NTPDC | Specifies that the primary domain controller of this domain is included.
NTBDC | Specifies that all backup domain controllers of this domain are included.

[machine list]

Entries in this section specify the computers on which the service is to be installed or controlled. Entries in this section have the following forms:

computer_name=parameter
computer_prefix*=parameter

computer_name

The exact name of a computer in the domain.

computer_prefix*

A common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. This form can only be used with the EXCLUDE parameter.

parameter

One of the following:

INCLUDE | Specifies that this computer is added to the list. INCLUDE is required for a computer to be managed when automatic detection is off. INCLUDE cannot be used with computer_prefix.
EXCLUDE | Specifies that this computer, or any matching computers, are excluded from the list, even if automatic detection is on.

[service account]

Entries in this section specify a service account to be used. Entries in this section have the following forms:

*=domain\account
*=account

domain

The name of the local or trusted domain where account exists.

account

An account with administrator access. This account is granted the Log on as a Service user right and added to the Administrators local user group by RSERVICE for each computer.

[service name]

The entry in this section specifies the name of the service to be remotely managed. This entry has the following form:

*=service_name

service_name

The name of the service. This name is used for both the system name and the display name if the service is installed by RSERVICE. If the service is installed by another method, then this name must be the system name of the service.

The service name must be identical to that which Service Control Manager uses to identify the service, not the display name.

[executable file]

Entries in this section specify the executable file of the service specified in the [service name] section. Entries in this section have the following form:

computer_name=executable_filename
computer_prefix*=executable_filename
*=executable_filename

computer_name

The exact name of a computer in the domain.

computer_prefix*

A common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

All computers not specified by computer_name or matched by computer_prefix*.

executable_filename

The name of the executable file for the service. Executable_filename cannot include a directory path; only the filename and extension are allowed; for example, SERVICE_NAME.EXE.

[installation directory]

Entries in this section specify the directory in which the executable file specified in the [executable file] section and the files specified in the [other files] section will be installed. Entries in this section have the following form:

computer_name=drive:\ path
computer_prefix*=drive:\ path
*=drive:\ path

computer_name

The exact name of a computer in the domain.

computer_prefix*

A common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

All computers not specified by computer_name or matched by computer_prefix*.

drive:\path

A path to the directory for the services. This path must be a drive letter path (for example, c:\rservice). If this directory does not exist, it is created if the service is being installed, and any access permissions specified in the [access permissions] section are set on the new directory. The files then inherit permissions from the directory.

[other files]

Entries in this section specify other files that are to be copied when the service is installed. For example, you may want to copy .DLL files required by the service, as well as the executable file specified in the [executable file] section.

All the files listed in this section are removed when the RSERVICE /deinstall command is used to remove the service.

Entries in this section have the following form:

computer_name=file[:drive:\path] [file[:drive:\path] ...]

computer_prefix*=file[:drive:\path] [file[:drive:\path] ...]

*=file[:drive:\path] [file[:drive:\path] ...]

where

computer_name

Is the exact name of a computer in the domain.

computer_prefix*

Is a common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

Specifies all computers not specified by computer_name or matched by computer_prefix*.

file

Specifies the name of the file in the source directory that is to be copied.

drive:\path

Specifies the directory on the remote computer to which the file should be copied. By default, files are copied to the directory specified in the [installation directory] section.

Note To copy the file into the SYSTEM32 directory, use %SystemRoot% instead of drive:\path.

For example:

*=xyz.dll qrt.dll abc.dll:c:\newservices\support

In this example, the files XYZ.DLL and QRT.DLL are copied from the source directory to the installation directory, and the file ABC.DLL is copied from the source directory to c:\newservices\support.

[startup parameters]

Entries in this section specify the startup parameters (arguments) for the specified computers. Entries in this section have the following form:

computer_name= parameter […]
computer_prefix*= parameter […]
*=parameter […]

computer_name

The exact name of a computer in the domain.

computer_prefix*

A common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

All computers not specified by computer_name or matched by computer_prefix*.

parameter […]

One or more service startup parameters separated by spaces. If a startup parameter includes embedded spaces, then the parameter must be surrounded by double quotes (for example, "parameter with space"). A parameter may also include a system environment variable, specified as %variable_name%, which is expanded to the computer-specific value when the service is started.

[automatic start]

Entries in this section specify whether the service should start each time the computer is started. Entries in this section have the following form:

computer_name=parameter
computer_prefix*=parameter
*=parameter

where

computer_name

Is the exact name of a computer in the domain.

computer_prefix*

Is a common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

Specifies all computers not specified by computer_name or matched by computer_prefix*.

parameter

Can be either of the following:

YES | Specifies that the service is to be installed on this computer with a startup type of Automatic.
NO | Specifies that the service is to be installed on this computer with a startup type of Manual. The default value is NO.

[access permissions]

Entries in this section specify the access permissions granted to the installation directory specified in the [installation directory] section and the files specified in the [executable files] and [other files] sections. Entries in this section must be in one of the following forms:

computer_name= user_group:access [user_group:access …]
computer_prefix*= user_group:access [user_group:access …]
*= user_group:access [user_group:access …]

where

computer_name

Is the exact name of a computer in the domain.

computer_prefix*

Is a common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name. When entries match more than one computer name, the parameter for the first match is used.

*

Specifies all computers not specified by computer_name or matched by computer_prefix*.

user_group

Is a user group name or user account. If this user group name or account is in a trusted domain then the name must be specified as domain\user_group or domain\account. If a user group or account name includes embedded spaces then the entire parameter must be surrounded by double quotes (e.g., "Backup Operators:READ".)

access

Specifies the directory and file access restriction for the user_group as one of the following:

FULL | All access.
CHANGE | Read, Write, Execute, and Delete access.
READ | Read access only.

For example:

[access permissions]

*=Administrators:READ "PrimoDomain\Domain Admins:FULL"

In this example, members of the Administrators local group on the client computer are granted read permissions, and the domain administrators for the domain PrimoDomain are granted full privileges, on the installation directory and the files installed with this initialization file.

[registry settings]

This section specifies Registry settings to be made during installation of the service. You can specify multiple settings by including multiple entries in this section.

Note The Registry settings are not changed when the service is removed using the RSERVICE \deinstall command.

Entries in this section have the following form:

computer_name= key:registry_path [type:name=value ...] [key:registry_path [type:name=value ...] ...]
computer_prefix*= key:registry_path [type:name=value ...] [key:registry_path [type:name=value ...] ...]
*= key:registry_path [type:name=value ...] [key:registry_path [type:name=value ...] ...]

where

computer_name

Specifies either the name of a specific computer to receive this change to the Registry, or an asterisk (*) to specify that all computers will receive this change to the Registry.

registry_path

Specifies the registry path to an existing key or a key to be created, for example

HKLM\Software\Microsoft\SMS\TRACING

The following abbreviations are allowed for the root of the path:

HKLM | HKEY_LOCAL_MACHINE
HKU | HKEY_USERS
HKCR | HKEY_CLASSES_ROOT

type

Specifies the data type for an existing registry entry. RSERVICE recognizes the data types DWORD, SZ, and EXPAND_SZ.

name

Specifies the name of the Registry entry.

value

Specifies the value of the Registry entry.

[source directory]

Entries in this section specify the directory from which the executable files specified in the [executable file] and [other files] sections will be copied. Entries in this section have the following form:

computer_name=drive:\ path
computer_prefix*=drive:\ path
*=drive:\ path

computer_name

The exact name of a computer in the domain.

computer_prefix*

A common prefix found in the names of one or more computers in the domain. The * is a wild-card that matches zero or more additional characters in a computer's name.

*

All computers not specified by computer_name or matched by computer_prefix*.

drive:\[path]

A path to the directory containing the service executable files.

Example RSERVICE Initialization File

[domain name]

engrdomain=listed

[machine list]

engrlab1=include

engrmary=include

engrjohn=include

station87=include

[service account]

*=masterdom\smsadmacct

[service name]

*=SMS_INVENTORY_AGENT_NT

[executable file]

*=invwin32.exe

[installation directory]

station87=d:\smsdir

engrlab*=e:\smsdir

*=c:\smsdir

[startup parameters]

engrmary=/L:\\smsengr02\sms_shr\ /T0

engrjohn=/L:\\smsengr03\sms_shr\ /T0

*=/L:\\smsengr01\sms_shr\ /T0

[source directory]

*=c:\smstest\rservice

[other files]

*=smsengr.dll

[access permissions]

*=Administrators:READ " masterdom\Domain Admins:FULL"

[automatic start]

*=yes

[registry settings]

*=key:HKLM\Software\Microsoft\SMS\TRACING DWORD:Enabled=1 key:HKLM\Software\Microsoft\SMS\TRACING\SMS_INVENTORY_AGENT_NT DWORD:Enabled=1 SZ:TraceFilename=c:\rservice\invagent.log


SHRPERM.EXE: Set Share Permissions

SHRPERM sets share permissions on Windows NT Server or Windows NT Workstation.

Runs On

Alpha, x86

Files Required for SHRPERM

SHRPERM.EXE

SHRPERM Syntax

shrperm \\machine\share user_or_group:permission[…]

\\machine\share

A universal naming convention (UNC) path to the server share or workstation share.

user_or_group

A user name or user group name.

permission

A permission setting:

r or read | Read(RX)
c or change | Change(RXWD)
f, full, or all | Full control


SRVINFO.EXE: Server Info

SRVINFO gathers and displays various information about a computer, such as available disk space and partition types. SRVINFO can be used on a remote computer.

Runs On

Alpha, x86 under Windows NT 4.0; x86 only under Windows NT 3.51

Files Required for SRVINFO

SRVINFO.EXE

SRVINFO Syntax

srvinfo server

server

The name of a server about which you want information.

SRVINFO Output Example

C:> srvinfo \\waitress02

Server Name: waitress02

Security: Users

NT Type: NT Advanced Server

Version: 4.0, Build = 1381, CSD =

Domain: WAITRESS

PDC: \\WAITRESS02

IP Address: 0.0.0.0

CPU[0]: x86 Family 5 Model 2 Stepping 5

Drive: C$

[File System] FAT

[Size] 1010 MB

[Free] 251 MB

Drive: D$

[File System] NTFS

[Size] 2048 MB

[Free] 784 MB

Services:

[Running] Alerter

[Running] Computer Browser

[Stopped] ClipBook Server

[Running] DHCP Client

[Running] EventLog

[Running] Server

[Running] Workstation

[Running] License Logging Service

[Running] TCP/IP NetBIOS Helper

[Running] Messenger

[Stopped] MSDTC

[Running] MSSQLServer

[Stopped] Network DDE

[Stopped] Network DDE DSDM

[Running] Net Logon

[Stopped] Network Monitor Agent

[Running] NT LM Security Support Provider

[Running] Plug and Play

[Running] Remote Access Autodial Manager

[Running] Remote Access Connection Manager

[Stopped] Remote Access Server

[Stopped] Directory Replicator

[Running] Remote Procedure Call (RPC) Locator

[Running] Remote Procedure Call (RPC) Service

[Stopped] Schedule

[Running] SMS_CLIENT_CONFIG_MANAGER

[Running] SMS_EXECUTIVE

[Running] SMS_HIERARCHY_MANAGER

[Running] SMS_INVENTORY_AGENT_NT

[Running] SMS_PACKAGE_COMMAND_MANAGER_NT

[Running] SMS_SITE_CONFIG_MANAGER

[Running] Spooler

[Running] SQLExecutive

[Running] Telephony Service

[Stopped] UPS

[Running] World Wide Web Publishing Service

[Running] SMS Remote Control Agent

Network Card [0]: Intel EtherExpress PRO Ethernet Adapter

Network Card [1]: Remote Access WAN Wrapper

Network Card [2]: Remote Access WAN Wrapper

Network Card [3]: Remote Access WAN Wrapper

Network Card [4]: Remote Access WAN Wrapper

Network Card [5]: Remote Access WAN Wrapper

Network Card [6]: PPTP Adapter

Network Card [7]:

Network Card [8]: Remote Access Mac

Network Card [9]:

Network Card [10]: Remote Access WAN Wrapper

Network Card [11]: Remote Access WAN Wrapper

Network Card [12]: Remote Access WAN Wrapper

Network Card [13]: Remote Access WAN Wrapper

System Up Time: 47 Hr 31 Min 13 Sec


TESTNET.EXE: Network Tester

TESTNET diagnoses network and name-resolution problems by performing many of the same enumeration API calls made by SITE_CONFIG_MANAGER.

Runs On

Alpha, x86

Files Required for TESTNET

TESTNET.EXE
SMSMFC.DLL
NETMSLM.DLL for Windows NT, LAN Manager,
and LAN Server domains and servers
NETNVNW.DLL for Novell NetWare domains and servers

This tool must be run from the directory in which the DLLs are located: SMS\SITE.SRV\platform.BIN.

TESTNET Syntax

testnet [netbase_DLL] [/c:account] [/l:[user]] [/z] /a
testnet [netbase_DLL] [/c:account] [/l:[user]] [/z] /s:server
testnet [netbase_DLL] [/c:account] [/l:[user]] [/z] {/d | /g | /u}:domain

/a

Gets information on all domains.

/c:account

Uses a specific set of credentials. TESTNET prompts for the account's password.

/d:domain

Gets information on servers in this domain (servers and shares).

/g:domain

Gets a list of global user groups for this domain.

/l[:attribute]

Forces a network logon on a server immediately after the server is validated. A specific attribute (privilege level, administrator share, etc.) can be specified.

/s:server

Gets information on this server (shares).

/u:domain

Gets a list of users for this domain.

/z

Displays additional messages for debugging.

netbase_DLL

Uses a specific netbase network-provider DLL.

/?

Provides a usage statement.


TLIST.EXE: Task List

TLIST displays the process IDs of all currently running applications.

Runs On

Alpha, x86

Files Required for TLIST

TLIST.EXE

TLIST Syntax

tlist [/t]

/t

Shows a tree view of the active processes (parent-child process relationships).


Job and Client Tools


ASSETMIF.EXE: Asset MIF Maker

ASSETMIF collects asset information from clients. ASSETMIF can also be used to assign a user-friendly name to NetWare clients. A LabAsset table is created in the SMS database.

ASSETMIF can be run manually on a client after clisetup.exe has been run, or it can be added to RUNSMS.BAT or smsls.bat after clisetup.exe is run and before inventory is taken.

Before running ASSETMIF.EXE, you must configure ASSETMIF.INI.

Runs On

Alpha, x86

Files Required for ASSETMIF

ASSETMIF.EXE
ASSETMIF.INI

ASSETMIF Syntax

assetmif

ASSETMIF.INI

In this version, the fields below are hard-coded; new ones won't be recognized. ASSETMIF.INI should be in the root of drive C:. It can be a hidden file.

[AssetMif]
IniVersion=1.0

[Identification]
LabAssetNumber=
MachineSerialNumber=
MachineName should match NetBIOS name. If NetWare, use what you like.
MachineName=
Comment=

[Location]
Building=
Room=
Bench=
Comment=

[Attributes]
RAM in kilobytes should match SMS inventory values.
An Alert can compare values.
RamInKbytes=
ExternalHardDriveCount=
InternalHardDriveCount=
Comment=


BADPENT.EXE: Bad Pentium Detector

BADPENT detects and reports clients that exhibit the FPU problem seen in some Pentium CPUs. BADPENT creates a MIF file, BADPENT.MIF, in the NOIDMIFS directory. There is package definition file, BADPENT PDF, in SMS\Clients\Win16, along with BADPENT.EXE. Use BADPENT PDF to create a package containing BADPENT to clients.

Runs On

x86

Files Required for BADPENT

BADPENT.EXE
BADPENT.PDF

BADPENT Syntax

badpent [/a] [/v]

/a

All. Reports good Pentium CPUs as well as bad ones.

/v

Verbose mode. More output is displayed on the screen.


BREAKFTM.EXE: Mirror Breaker and Restorer

A mirrored system drive causes the Windows NT 4.0 Unattended Upgrade to fail. Therefore, the mirror must be broken before upgrading.

BREAKFTM breaks the system mirror before the Windows NT Server 4.0 upgrade, then recreates the mirror once the upgrade is finished. BREAKFTM has no effect on computers that do not have a system mirror.

Use BREAKFTM only with Windows NT Server 4.0 Unattended Upgrade. To break or create a mirror manually, use Disk Administrator in Administration Tools (Windows NT Server version only). Do not use BREAKFTM while using Disk Administrator.

BREAKFTM can recover mirrors only if they were broken by BREAKFTM.

BREAKFTM can be run either through SMS or directly from a command prompt.

Runs On

Alpha, x86

Files Required for BREAKFTM

BREAKFTM.EXE
BREAKFTM.PDF

BREAKFTM Syntax

breakftm [/b] [/r] [/d drive_letter:] [/sms]

/b

Breaks the mirror, then restarts the computer.

/r

Restores the mirror, then restarts the computer.

/d drive_letter:

Specifies the drive to break or restore. The default is the system drive.

/sms

Use this option when calling BREAKFTM from SMS.

/?

Provides a usage statement.

BREAKFTM Error Correction

BREAKFTM creates a hidden file called mirrorbk.dat in the Windows NT system directory; this file contains the original mirror information needed to restore the mirror. If this file is removed, the mirror cannot be restored.

After the mirror is broken and the system is restarted, the system drive appears as a normal partition. The shadow has no drive letter assigned to it, but is visible from Disk Administrator.

If an error occurs while restoring the mirror, the mirror can be reestablished manually through Disk Administrator. To re-create the mirror manually, delete the shadow partition (the partition with no drive letter assigned) and use the free space to re-create the mirror. (See Disk Administrator help for more information.)

BREAKFTM Output Messages

Success No Mirror to Break. The system partition is not a mirror.

Success Mirror Broken. The system mirror was broken successfully.

Success Mirror Recovered. The system mirror was recovered successfully.

Success There Was No Mirror To Recover. The system partition was not a mirror originally.

Usage error in calling breakftm.exe. Usage error in calling breakftm from the command line.

Error occurred while parsing the registry. Could not get the disk information out of the registry key. The disk key in the registry might be corrupt or missing. The mirror was not broken or recovered; do it manually.

Error occurred while parsing the partition table. The information in the partition table was not what was expected. The mirror was not broken or recovered; do it manually.

Drive letter was invalid. The specified drive letter is not valid, or the system drive letter is incorrect. The mirror was not broken.

Unknown registry version. The disk registry key is of a version not recognized by breakftm. Break the mirror manually.

Drive letter was not a mirror or simple partition. The requested drive letter is not associated with a mirrored configuration, possibly indicating that a simple partition is in use.

Mirror was initializing. The mirror could not be broken because it was initializing. Wait for the initialization to complete and retry.

Mirror is unhealthy. The mirror could not be broken because it was unhealthy. See Disk Administrator help for more information.

Could not read mirror data from file mirrorbk.dat. The hidden file mirrorbk.dat is corrupt or missing. The mirror was not recovered; do it manually.

Drive letter does not match drive letter of broken mirror. The system drive letter has changed. It is unsafe to recover the mirror using breakftm; do it manually.

Current partition table does not match stored mirror data. The partition information on the drives has changed after breaking the mirror. It is unsafe to recover the mirror using breakftm; do it manually.

Current registry does not match stored mirror data. The partition information in the registry has changed after breaking the mirror or is missing. It is unsafe to recover the mirror using breakftm; do it manually.

Unexpected Win32 error code. An unexpected Win32 error occurred. The mirror was not broken or recovered. You can retry, or do it manually.

Unknown error occurred. The mirror was not broken or recovered. You can retry, or do it manually.

Using BREAKFTM with SMS

There are two setup variations for BREAKFTM in BREAKFTM.PDF: Break System Mirror and Recover System Mirror. Schedule Break System Mirror immediately before a Windows NT Server 4.0 upgrade. Schedule Recover System Mirror immediately after a Windows NT Server 4.0 upgrade. BREAKFTM has no effect on nonmirrored systems, so it can be safely used with any Windows NT Server 4.0 upgrade.


CLIOPTS.EXE: Client Options Setter

Clients have special options to control the transport protocol used by the Help Desk and Diagnostics components. During client setup, these options are read from SMS.INI for the wuser, usertsr, and useripx command lines.

CLIOPTS /SET sets the usertsr, useripx, or wuser options so that they can be preserved during upgrade or execution of SMSRUN16.EXE. CLIOPTS /SET overwrites previous option settings, except /w on usertsr, which cannot be changed by CLIOPTS. In addition to setting option values, CLIOPTS sets [Local] SetupPhase=verify_files to force CLISETUP to rewrite the new option values.

Changes do not take effect until Windows is restarted. For usertsr, the computer must be restarted. The first time Windows is restarted, CLIENT.BAT gets the new usertsr value, but CLIENT.BAT then requires a computer restart to start usertsr with the new value. See the example.

CLIOPTS can also be distributed as a PCM job. There is no PDF currently available, but a batch file containing the needed options can be written.

CLIOPTS is a 16-bit application.

Runs On

Alpha, x86

Files Required for CLIOPTS

CLIOPTS.EXE

CLIOPTS Syntax

cliopts /set option option_value
cliopts /list option

/set

Sets the named option to the specified value in SMS.INI.

/list

Lists the current value of the named option in SMS.INI.

option

The name of an option in SMS.INI.

option_value

The value to set for the named option.

CLIOPTS Example

To change the Lana number to Lana 1 on Windows for Workgroups:

cliopts /set usertsr /L1

cliopts /set wuser /L1

Quit and restart Windows.

Quit windows again, then restart the computer.

SMS.INI would contain these values:

[Options]

usertsr=/L1

wuser=/L1

[Local]

SetupPhase=verify_files


EXECUTE.EXE: Application Executer

EXECUTE runs a two-phase setup program under Package Command Manager (PCM). A two-phase setup is two different programs; the first program starts the second one and then the first one exits. When the first program exits, PCM severs its network connection, leaving the second program without a network connection.

EXECUTE runs the command line for a Windows program, and then polls for its termination. Upon termination, EXECUTE temporarily pauses and waits until no window with the specified window title and window class can be found. (Use SPY.EXE, distributed with Microsoft Visual C++ 1.5, to determine the window class and title for the second phase of a setup application.)

EXECUTE.EXE must reside either in the root directory of the package share, or the logon server MSTEST directory: logon.srv\MSTEST.

Restrictions

EXECUTE is only for 16-bit applications running on Windows 3.1, Windows NT, or Windows 95.

Runs On

Alpha, x86

Files Required for EXECUTE

EXECUTE.EXE

The file EXECUTE.EXE can be found in SMS\SITE.SRV\MAINCFG.BOX\MSTEST? on the SMS site server..

EXECUTE Syntax

execute "command_line" "window_caption" "window_classname"

command_line

The command line to be executed.

window_caption

The string to appear in the title bar of the window running command_line. This can be empty (" "), but not omitted.

window_classname

The name of a window class. This can be empty (" "), but not omitted.

EXECUTE Examples

execute "SETUP.EXE /B4" "Microsoft PowerPoint" "PPApplicationClass"

execute "SETUP.EXE /B4" " " "PPApplicationClass"


FERRET.EXE: Compaq Info

FERRET reports information that can be detected on Compaq computers supporting Compaq AssetControl. This information is beyond that reported by SMS, and includes certain data stored in the BIOS (see Compaq documentation for specific information on setting up the BIOS):

  • Monitor serial number
  • System serial number
  • System board revision level
  • Manufacturer
  • Model
  • Asset tag

FERRET writes a NO_ID MIF file that is collected by the Inventory Agent as part of its normal operation. FERRET requires the existence of a correct SMS.INI file on the computer so that it can properly generate the NO_ID MIF file, and it also requires that the computer is running Compaq AssetControl. If FERRET is run on a non-AssetControl computer, it simply exits.

Use FERRET.PDF to create Package Command Manager jobs to run FERRET on appropriate computers. Put FERRET.EXE and the vendor-specific mapping file in the package source directory for FERRET. The file for Compaq computers is CPQBSSA.TXT. All of these files can be found in \BORK\SMS\CLIENTS\WIN16.

Runs On

x86

Files Required for FERRET

FERRET.EXE
FERRET.PDF
CPQBSSA.TXT

FERRET Syntax

ferret [/v]

/v

Verbose mode. More output is displayed on the screen.


ISIDIS.EXE: IDIS_NT Checker

ISIDIS checks whether the IDIS video driver, IDIS_NT.DLL, is installed on Windows NT 3.51 for remote control. IDIS_NT.DLL enhances video performance for Windows NT 3.51 remote control.

Runs On

Alpha, x86

Files Required for ISIDIS

ISIDIS.EXE

ISIDIS Syntax

isidis

/?

Provides a usage statement.


NETBOOT.EXE: Network Boot Disk Generator

NETBOOT creates and configures a netboot floppy disk. Such a disk, when inserted in a computer, detects and can use a variety of network cards and network protocols, prompts for a user name and password, and logs you onto the network.

The NETBOOT GUI, NetBoot Administrator, contains folders in the left-hand pane. When you select a folder, the objects it contains are shown in the right-hand pane.

Runs On

x86

Files Required for NETBOOT

APADMIN.MDB
APSNET.DLL
FLOPPY\DRIVERS\CENDIS.EXE
MFC040D.DLL
MFC042D.DLL
MFC40D.DLL
MFC42D.DLL
MFCD40D.DLL
MFCD42D.DLL
MSVCR40D.DLL
MSVCRTD.DLL
NETBOOT.EXE

Making a Floppy

By default, all net adapters and all protocols are selected. Therefore, to make a floppy containing all net adapters and protocols, from the Floppy menu, choose Build.

If you want to save space on a floppy disk, you can disable a net adapter or protocol by double-clicking it, which opens its Properties box, and deselecting Use This Device?

Changing Default Settings

The Default Settings object contains global configuration data.

General Tab

The General tab has the following items:

  • User. The contents of this field is placed in the Username field of the logon UI on the floppy. A valid username is expected.
  • Domain. The contents of this field is placed in the Domain field of the logon UI on the floppy. This must be a Windows NT domain name.
  • Protocol. The protocol selected here is used as the default protocol in the logon UI on the floppy. The supported protocols are defined in the Protocols folder.
  • Redirector. The redirector selected here is used as the default on the floppy:
    • BASIC: Does not support specific domain logons.
    • FULL: Requires a domain name.
  • UNC Path to a DOS Environment. This field specifies a complete UNC path to a globally available directory that has two subdirectories: DOS and BIN. The DOS directory contains any MS-DOS 6.22 files that you would like to make available to users of the floppy (you should at least have doskey.exe). The BIN directory contains any other DOS tools you would like to provide.

    This field can be empty, in which case this feature is disabled.

Domain List Tab

  • In the Domain List Tab, enter the names of the Windows NT user account domains available on your network. (This list need not be comprehensive.)

Note Be sure to click Add for each domain you enter.

Changing a Net Adapter's Properties

A Net Adapter object describes a net adapter to the floppy.

Device Properties Tab

The Device Properties tab has the following items:

  • Display Name. The descriptive text displayed to the floppy user.
  • Adapter Name. Used in protocol.ini to represent this adapter. It must be unique.
  • Driver Name. The internal identifier of the driver file. (This can be gleaned from the sample protocol.ini file often provided with a driver.)
  • Driver File. The contents of this field are placed in the value of the netcard line of the [network drivers] section of system.ini.
  • Script File. Indicates that the specified file is a script that performs further adapter-specific configuration.
  • Files to Extract. A list of files that the adapter requires on the floppy. These files must be in the floppy\drivers directory so they can be compressed onto the floppy.
  • Use This Device? Allows an adapter to be left off the floppy to save space, without deleting the information in this Properties box.
Device Settings Tab

In the Device Settings tab, enter the names of the settings needed in protocol.ini to configure this adapter. Then enter the default values for each setting. Use the up and down arrow buttons to sort values. The value at the top of the list is the default value used by the floppy.

Note Be sure to click Add for each setting and value you enter.

Device Detection Tab

The Device Detection tab is for advanced users only. This dialog is not supported.

Changing a Protocol's Properties

A Protocol object describes a network protocol to the floppy.

Device Properties Tab

The Device Properties tab contains the following items:

  • Display Name. The descriptive text displayed to the floppy user.
  • Adapter Name. Used in protocol.ini to represent this protocol. It must be unique.
  • Driver Name. This is the internal identifier of the driver file. (This can be gleaned from the sample protocol.ini file often provided with a driver.)
  • Driver File. The contents of this field are placed in the value of the transport line of the [network drivers] section of system.ini.
  • Script File. Indicates that the file specified is a script that does further protocol-specific configuration.
  • Files to Extract. A list of files that the protocol requires on the floppy. These files must be in the floppy\drivers directory so they can be compressed onto the floppy.
  • Use This Device? Allows a protocol to be left off the floppy to save space, without deleting the information in this Properties box.
Device Settings Tab

In the Device Settings tab, enter the names of the settings needed in protocol.ini to configure this protocol. Then enter the default values for each setting. Use the up and down arrow buttons to sort values. The value at the top of the list is the default value used by the floppy.

Note Be sure to click Add for each setting and value you enter.

Initialization Tab

In the Initialization tab, enter the DOS commands that will initialize this protocol properly. These commands are used in a batch file on the floppy.

Object Management

The left pane of NetBoot Administrator contains folders. Each folder contains objects. Selecting a folder reveals its objects in the right pane of NetBoot Administrator.

To Add an Object to a Folder

Right-click in an empty part of the right pane.

From the pop-up menu, choose New. The new object is called New_Object.

Edit the name by selecting it to highlight it, then clicking the highlighted name and typing. (If the second click occurs too soon after the first, it is interpreted as a double-click, which opens the object's Properties window.)

To Remove an Object from a Folder

Right-click on the object.

From the pop-up menu, choose Delete.

To Open an Object

Double-click on the object.

or

Right-click on the object.

From the pop-up menu, choose Properties.

NETBOOT Syntax

netboot


NWATTRIB.EXE: NetWare Sharable Attribute Setter

When distributing a package whose source directory is on a NetWare server and distribution server is a NetWare server, SMS is not able to retain the shareable file attribute. NWATTRIB solves this by setting the shareable file attribute on files of a previously distributed package to match the attribute settings of the files in the package source directory.

Note A file attribute setting of no attributes (also called a normal attribute setting) is identical to a setting of the NetWare shareable attribute only. Because these two settings cannot be distinguished, files in a source directory with either setting are skipped; no changes are made to those files in the package directories. To avoid this, preset the archive attribute on all files in the source directory prior to setting the shareable attribute.

Runs On

Alpha, x86

Files Required for NWATTRIB

NWATTRIB.EXE

NWATTRIB Syntax

To set the attributes of the files in an SMS package on NetWare distribution servers to be the same as the attributes of the files in a source directory:

nwattrib /p:package_ID /d:source_dir [/ss:site_server] [/s] [/v]

To set the attributes of the files in an SMS package on NetWare distribution servers to be the same as the attributes in an attribute map file:

nwattrib /p:package_ID /a:attribute_map [/ss:site_server] [/v]

To write an attribute map file (which can be edited and used as input in the preceding command) containing a map of the attributes of the files in a source directory:

nwattrib /d:source_dir /a:attribute_map [/ss:site_server] [/s] [/v]

/a:attribute_map

Specifies a path to an attribute map file. If used with /d:source_dir, then a map of the attributes is written to attribute_map. If used with /p:package_ID, then attribute_map is used as input to set the attributes of the files in the package directories.

/d:source_dir

Specifies a path to a package source directory, which can be on a remote computer.

/p:package_ID

Specifies an SMS package ID, which determines which NetWare distribution servers and which package directories are used.

/ss:site_server

Specifies a site server. The default is the computer running NWATTRIB.

/s

Includes files in all subdirectories of the source directory and package directories.

/v

Verbose mode. More output is displayed on the screen.

/?

Provides a usage statement.


REMFPROT.EXE: F-PROT TSR Remover

If the virus-scanning software F-PROT is installed on a computer running Windows 3.11, the call to the F-PROT TSR must be removed from AUTOEXEC.BAT and WIN.INI before upgrading to Windows 95. REMFPROT removes the call to the F-PROT TSR, and a few other TSRs, from AUTOEXEC.BAT and WIN.INI.

REMFPROT returns errorlevel 1 if it fails to remove the TSR calls.

Runs On

x86

Files Required for REMFPROT

REMFPROT.EXE

REMFPROT Syntax

remfprot


Introduction

Welcome to the Microsoft Exchange Server Resource Guide, Supplement One. This guide is designed for people who are, or who want to become, expert users of Microsoft® Exchange Server and Microsoft Exchange Client.

The Microsoft Exchange Server Resource Guide, Supplement One is a technical supplement to the documentation included as part of the Microsoft Exchange Server product and does not replace that information as the source for learning how to use Microsoft Exchange Server.


About the Resource Guide

This guide includes the following chapters:

Chapter 1, "Planning and Setup," explains how to plan for efficiently adding users to Microsoft Exchange Server. It also describes the factors affecting performance and how to automate the installation process.

Chapter 2, "Working with Microsoft Exchange Server," describes how to maintain Microsoft Exchange Server and Microsoft Exchange Client. It includes information about using Russian, Eastern European, Greek and Turkish language character sets, Message Transfer Agent (MTA) routing, and procedures for moving Microsoft Exchange Server to another computer.

Chapter 3, "Optimizing Performance," discusses how to optimize the performance of Microsoft Exchange Server by balancing server and hardware resources, and by adjusting software settings.

Chapter 4, "Microsoft Exchange Server Disaster Recovery," describes data recovery techniques that can be applied to Microsoft Exchange Server for the quickest possible data recovery in the event of a system crash or another disaster.

Chapter 5, "Application Development," provides examples of custom solutions that can be developed for Microsoft Exchange Server. Development of custom solutions can range from modifying existing sample applications to using high-end development tools to create more complex groupware applications.

Chapter 6, "Microsoft Exchange Server Registry Reference," identifies registry values that can be used to configure Microsoft Exchange Server.

Chapter 7, "Troubleshooting Microsoft Exchange Server," provides information about troubleshooting problems with Microsoft Exchange Server and Microsoft Exchange Client.


Microsoft BackOffice Resource Kit, Part Two Compact Disc

The Microsoft BackOffice™ Resource Kit, Part Two compact disc contains Microsoft Exchange Server tools and related online documentation.


Web Sites

Visit the following sites on the World Wide Web for up-to-date information about Microsoft Exchange Server:

http://www.microsoft.com/exchange

The Microsoft Exchange Server Web site contains up-to-date information about Microsoft Exchange Server and links to other Microsoft BackOffice products.

http://www.microsoft.com/syspro/technet/boes/bo/mailexch/exch/tools/appfarm/appfarm1.htm

The Microsoft Exchange Server Application Farm Web site includes sample applications and other development tools that enable you to develop your own applications for Microsoft Exchange Server.

http://www.microsoft.com/support/products/backoffice/msmail.htm

The Microsoft Exchange Server Technical Support Web site gives you access to the Microsoft Exchange Server Knowledge Base, support information, and frequently-asked questions.

http://www.microsoft.com/technet

The Microsoft TechNet Web site contains information about subscribing to Microsoft TechNet, which provides in-depth technical information about Microsoft business products, including Microsoft Exchange Server and other Microsoft BackOffice products.

http://www.microsoft.com/train_cert

The Microsoft Training and Certification Web site provides information about training options and the Microsoft Certified Professional Program.


Conventions in This Manual

The following table summarizes the typographic conventions used in the Microsoft Exchange Server Resource Guide, Supplement One.

Convention | Description
bold | Menus and menu commands, command buttons, property page and dialog box titles and options, command-line commands, options, and portions of syntax that must be typed exactly as shown.
Initial Capitals | Names of applications, programs, and named windows.
italic | Information you provide, terms that are being introduced, and book titles.
KEY+KEY | Key combinations in which you press and hold down one key and then press another.
monospace | Examples, sample command lines, program code, and program output.
SMALL CAPITALS | Names of keys on the keyboard.


Contributors

This book is dedicated to all the hardworking writers, editors, reviewers, and numerous production staff people at Microsoft who make books like this possible. Thank you!

Contributions to this book include the following:

Contributing Writers:
Scott Briggs, Kali Buhariwalla, Jim Chismar, Sukvinder Singh Gill, Brian Mahoney, Joseph Pagano, Joseph Roberts, Rob Sanfilippo, Eric Savoldi, Dean Simpson, Len Wyatt

Technical Consultants:
Susan Nellis, Steven Bailey, John Baker, Michael Bird, Adam Blum, Scott Briggs, Kali Buhariwalla, John Coleman, Rick Cook, KC Cross, Andrei Davydov, Tom DeFeo, Jaime Emmanuelli, Alan Erickson, Ken Ewert, Ian Farrell, Deb Ferrell, Bob Gering, Rob P. Gilmore, David Goodhand, Robert Hughes, Phillip Hupf, Brent Jensen, Martin Kohlleppel, John Kozell, Elizabeth Kutler, Johnny Lee, Stephen Leverett, Eric Lockard, Ann McCurdy, Thomas McInerney, Tony Meleg, Paul Moore, Patti Moree, Brian Murphy, Mahesh Nasta, Noel O'Flarity, Joe Orzech, Scott Paulson, Vanitha Prabhakaran, Mark Pustilnik, Jim Reitz, Tom Rizzo, Joseph Roberts, Angela Schmeil, Joel Soderberg, Andrzej Turski, Jithendra Veeramachaneni, Edmond VonAllmen, Dick Vorhees, Daniel Weisman, Cathy Westman

Technical Writer:
Candy Paape

Technical Editors
Connie La Chasse, Sharon Farrar


Chapter 1 Planning and Setup

This chapter describes methods to consider when planning your rollout and setting up Microsoft Exchange Server. It also explains how to configure Microsoft Exchange Server to run at optimum performance and how to automate the installation process.


Adding Users to Microsoft Exchange Server

There are a number of performance-related issues involved in adding users to a Microsoft Exchange Server organization.

Users vary widely in their messaging, scheduling, and workgroup usage levels. Individual usage patterns, schedules, and activity levels depend upon the degree to which e-mail, group, and personal scheduling and public folder applications are used for business and personal activities within the organization.


Number of Users Per Server

The main factor in determining the number of users a Microsoft Exchange Server computer can support is the load each user places on the server. This dependency generally falls into two distinct categories: user-initiated actions and background actions.

Some users interact with the server for 12 hours at a time, while others connect to the server only once a week for a few minutes. Some users read hundreds of messages in dozens of public folders every day, while others read none at all. In a given user community, a small percentage of users can generate a disproportionate percentage of the total load on a server because they are the heavier, more aggressive users.

User-Initiated Actions

When a user interacts with the server directly, the actions performed place an immediate incremental load on the server for a duration of time. User-initiated actions are operations that the server performs as a direct result of a user's action, and are synchronous from the user's point of view. For example, opening an unread message in a private folder in the server information store entails processing time on the server to receive and interpret the open request. The server must evaluate access restrictions, retrieve the message from the database, mark the message as unread, update the unread count for the folder, return the requested message properties to the client, and generate a folder notification to the client. All of this happens in the time it takes for the remote procedure call (RPC) issued by the Microsoft Exchange Client to return control to the client. The actual time that the user perceives the operation takes is this time, plus the additional processing time needed by the client to draw the window, display the message properties, and so on.

User-initiated actions are the single most important factor in sizing a Microsoft Exchange Server computer. The performance of any given server is directly proportional to the number of users actively interacting with the server per unit time and the actions performed.

Background Actions

In addition to user-initiated actions, Microsoft Exchange Server performs asynchronous or background actions on behalf of users. Accepting, transferring and delivering messages, making routing decisions, expanding distribution lists, replicating changes to public folders and directory service information, executing rules, monitoring storage quotas, and performing background maintenance such as deleted messages collection and view index expiration, are all examples of the work a server can do asynchronously on behalf of users, whether or not they are currently connected to the server.

In general, the load on the server due to background actions such as user-initiated actions, is proportional to the number of users on the server. However, other factors such as whether the server acts as an intersite connector for messages on other servers or hosts a messaging gateway, can have a large impact. On Microsoft Exchange Server computers that act purely as gateways or backbone computers and do not directly host any users, the load due to user-initiated actions is essentially non-existent. In such cases, the load on the server is considered only as a background action.

Inequality of Actions

Although it is often convenient for modeling purposes to think of every user-initiated or background action as being equivalent to every other in terms of the load that each places upon the server, this is not the case. For example, when a 500K message is copied to a user's personal information store, that action places more load on the server than if a 1K message were copied. Similarly, sending a message to a distribution list containing 100 members creates more background actions than sending the message to a single recipient.

You can make accurate predictions about how user-initiated actions will impact the server load if you base your predictions on aggregates over time. For example, if you review the set of actions a user performs during a certain time period, such as an 8-hour work day, you can sum up the user-initiated actions during that time period. You can also quantify some definitions of users by characterizing how many actions they perform per unit time, the set of actions and the individual action's load characteristics (such as estimating the size of messages) and arrive with sample user definitions that can be used for making rough performance predictions of actual user communities.

As an example, you can classify your users as having low, medium, and heavy usage.

A low-usage user could be someone who, on a daily average:

  • Sends three messages
  • Reads new mail five times and old mail 12 times
  • Makes one change to his or her schedule

A medium-usage user, on a daily average:

  • Sends six messages
  • Reads new mail 15 times and old mail 12 times
  • Makes five changes to his or her schedule

A heavy-usage user, on a daily average:

  • Sends eight messages
  • Reads new mail 20 times and old mail 12 times
  • Makes 10 changes to his or her schedule


Types of Users

As mentioned above, traffic and interaction patterns vary greatly. Some organizations rely heavily on their messaging system, which creates very heavy user interaction. Other organizations may not rely so heavily on the messaging system and therefore have low usage levels. The demand your users place on Microsoft Exchange Server has a direct impact on performance and the number of users that can be hosted on one computer. The same hardware, performing the same functionality, can host 500 light users in one organization, but only 150 heavy users in another organization.


Server Load

A server computer consists of the following three hardware elements: one or more CPUs of a given architecture and processing speed, an amount of primary memory (RAM), and one or more disk drives of specific speeds and sizes and their controllers. These hardware elements comprise the critical hardware resources on the server.

When Microsoft Exchange Server services a user-initiated action or performs background actions, it uses each of these resources to some degree over a period of time to perform its operations. For example, responding to an open message request from a client can require several milliseconds of CPU processing time, one or more disk accesses, and enough memory to hold the code and data necessary to perform the operation. In the case where actions occur over a period of time, all of the server hardware is dedicated to each action. Each action is completed as quickly as possible and does not need to wait for hardware resources to become available. In such cases, the Microsoft Exchange Server computer is essentially idle between each action, and the actions are separated sufficiently in time so that they do not overlap. In other words, the server is unloaded.

On the other hand, when many users are initiating actions close together in time or a large number of background events are occurring, there is competition for the server hardware resources. Bottlenecks occur when the code servicing a particular action must wait for hardware to become available to complete its tasks. When this happens, the server is said to be under load.

Load and Response Time

When a server is under load, actions can take longer to complete than they would if the server were unloaded. For user-initiated actions, this can increase response time. If the server is excessively loaded, users can perceive the server as slow or unresponsive. Imagine a server with specific hardware and a homogenous user community where each user performs the same set of actions randomly but, on average, evenly spaced over a given time interval. With only a single user connected to the server, each user-initiated action is completed before the next is initiated. The response times that user experiences are near the theoretical minimums allowed by the hardware in use on the client and server computers and the underlying network.

However, if you allow more users to connect to the server, actions overlap in time. Microsoft Exchange Server becomes bottlenecked for short durations while one portion of the software performing an action waits for another to relinquish hardware resources. Eventually, this delays actions to the point that user-initiated actions are taking noticeably longer to complete.

This relationship between load and response time defines the number of users any given server can support. At some point, as the load on a server increases, the response times a user experiences move from being acceptable to being unacceptable. This crossover point defines the number of the theoretical, homogenous users that a server's hardware can support.

An Average Workday's Effect on the Server

Actions that cause load are not evenly distributed over time. The morning hours of the workday can exhibit the highest load, when users arrive at work and spend time catching up on e-mail or public folder information that has been generated since the previous day. Conversely, lunch time can represent a lull in the day's activity, as well as evenings and weekends.

Given the number of users Microsoft Exchange Server can typically host, even on smaller server computers, the impulse loads should not represent a large percentage of the total user population on the server except in extreme situations.


Factors Affecting Performance

The type and number of CPUs attached to a Microsoft Exchange Server computer dictate the performance potential for the Microsoft Exchange Server environment. For example, computers based on the Pentium processor offer better performance than computers based on the 486 chip. Also, a 133MHz Pentium performs better than a 100MHz Pentium.

Paging can be viewed as a contention for memory. As with most resources, some contention is tolerable. However, as the contention increases, the system eventually reaches a point where system resources (such as CPU time, bus bandwidth, disk time, and so on) are increasingly passing pages back and forth among the various processes contending for memory. If you were to graph memory contention versus average response times, you would see a smooth line from zero contention up to a point where response times start to increase dramatically. This is often called thrashing. As memory contention increases past the point of thrashing, response times typically increase exponentially. Short periods of thrashing can be acceptable for some environments, but you should try to prevent systems from thrashing, especially during active, mission-critical activities.

I/O Subsystem

When examining the input/output (I/O) subsystem as it relates to performance, there are many factors to consider, such as the type and number of disk controllers, the type of drives installed, and the choices required for fault tolerance. Overall system performance on a Microsoft Exchange Server computer can be dramatically affected by these variables.

It is important to use all available small computer system interface (SCSI) channels and to add more channels, if necessary, to improve performance. Also, the addition of more disk drives can help performance. By adding more drives, you can ensure that the workload is distributed more efficiently.

Network Hardware

For optimal network performance, consider adapter types and the type of network medium, such as twisted-pair wire, optical fiber, coaxial cable, and so on. To optimize performance you can: install a high-performance network adapter card in the server; use protocols that are necessary and keep them to a minimum; use multiple network cards; and segment the LAN, if appropriate. Network adapters can provide varying levels of performance. The characteristics of an adapter that can most affect performance involve the bus type, bus width, and the amount of onboard memory on the adapter.


Microsoft Exchange Factors Affecting Usage

When determining the number of users to allow on a Microsoft Exchange Server computer, consider how many users will be connected simultaneously. You might be able to put more user accounts on one server if you know that not all of them will be connected at the same time. For example, if your organization has two shifts of workers, where both sets of users won't be connected to the server at the same time, then more user accounts can be hosted on the same server.

Although a background cost exists when you have more users on a server than are actually connected, it isn't nearly as high as the cost of having more simultaneously connected users.

In summary, the most important comparison to consider is that of background tasks versus user-initiated tasks. Even when a user is not connected, directories will be updated, rules triggered, messages delivered, and other operations will take place on an ongoing basis.

Location and Use of Stores

Microsoft Exchange enables users to store messages in the server-based store or in personal folder (.pst) files on their local computers or on a network drive. Even if a user has personal folders, he or she will also still have a server-based store. In fact, it is not possible for a user to only have personal folder files. The server-based store must exist to receive messages, process rules, and so on. However, if users set their personal folder files as the default delivery location, a lot of work is offloaded from the server. Messages are delivered to the user's server store and rules are triggered on behalf of that user, but these rules can be deferred until the user logs on, if it involves working with the user's .pst file.

Whenever a user requests data from a personal folder, the server does not read the attributes and data into the buffer cache. Instead, all of the processing occurs on the client, because that is where the data is located. In this case, the server does not have to be involved at all. If a user saves a copy of everything in the Sent Mail folder, that process is performed locally. Also, when a user deletes a message, a copy is saved in the local Deleted Items folder and again, the server is not involved.


Public Folder Use and Replication

Using public folders on a Microsoft Exchange Server computer can have a dramatic effect on the server's performance. Size, frequency of user access, various views on that folder, the number of replicas, the replication schedule, and how often its content changes are all factors that affect server performance. If many users access a public folder frequently, then the server is going to be kept busy satisfying those requests. Also, the public folder keeps track of the expansion state of each folder and the read/unread state of each message on a per-user basis.

Although public folder replication is a fast process, changes to a public folder are replicated according to the replication schedule set up by the administrator. Even if the replication schedule is set to Always, replication only occurs every 15 minutes. This affects the user because if replication starts when a user is accessing a public folder or the public folder hierarchy, the user will notice a sudden slowdown that improves only when the replication process is completed. If there are a number of public folder replicas to update, then this activity can place even more stress on the server and extend the replication process.

Public folders can contain messages and free-standing documents. Messages are like any other mail message as far as the resources they consume on a server. Free- standing documents, however, raise another issue for performance because they are typically large.

If you post a 1-MB file in a public folder, then any user that accesses that document brings 1 MB of data across the wire. This affects the performance of the server for every user.


Rules and Views

Rules are user-defined actions that require a server to perform on behalf of the user. Typical examples of rules are: displaying a notification when a message is received from a specific person, or automatically moving messages into a specific folder based on the content of the message. Typically, rules have very little effect on overall server performance until most users have more than 10 rules set up.

For views, the server must store and keep track of the indexes that make up a view. Although a cache is used to store the most recently used indexes, a user might notice a small performance hit when opening a seldom-used view.


Microsoft Schedule+

Schedule+ uses a hidden public folder to replicate free/busy information. Within a site, this replication occurs automatically. Between multiple sites, this replication must be set up by the administrator.

The main performance consideration for an administrator working with Schedule+ is whether the user is working with a local schedule file or a server schedule file. If a local file is used, Schedule+ is very responsive and periodically updates the schedule information on the server. However, if a user chooses not to work with a local schedule file, then each change to that schedule causes interaction with the server. Initial testing has shown that not working with a local schedule file causes a significant impact on the users, and if enough users are working in this manner, then it has a negative performance impact on all users.


Connectors and Gateways

Connectors and gateways are processes that run on the server. They both contend with Microsoft Exchange processes for resources on the server. These connectors and gateways communicate directly with the information store, which also creates contention for resources.

If a particular connector or gateway is causing performance problems, you can dedicate a computer to this connector or gateway, or add a second connector or gateway instance somewhere else in the site.


Directories, Replication, and the Bridgehead Server

A bridgehead server acts as the door in and out of the site's directory. When you configure a directory replication connector between two sites, you can choose which server in each site will act as the bridgehead server. It is the responsibility of this bridgehead server to exchange all directory updates with the partner bridgehead server. Within a site, directory replication occurs among all servers. Because this processing is proportional to the number of directory changes that occur, it is difficult to predict how it will affect the overall performance of a server. During a migration to Microsoft Exchange Server, when the directory is changing often, or in organizations where hundreds of directory updates occur every day, the directory replication process can negatively impact performance.


Message Transfer Agent

The main responsibility of the message transfer agent (MTA) is to route messages between multiple servers. Even in a single-server scenario, the MTA also has tasks to perform, including the expansion of distribution lists and the routing of outgoing gateway or connector messages. The MTA has the greatest impact on performance when multiple Microsoft Exchange Server computers are deployed.


Network Quality and Connectivity

If you place a Microsoft Exchange Server computer on a Fiber Distributed Data Interface (FDDI) ring with a 100-MB capacity, that server will provide better connectivity and performance than a server attached to a token-ring network. An overloaded Ethernet segment with many collisions occurring will also reduce the performance of the server. Wide area network (WAN) connectivity and quality should also be considered, especially if you are trying to determine site boundaries or whether to have clients access their server across the WAN.


Determining Server Limits

There is no explicit limit on the number of users you can configure to reside on a single Microsoft Exchange Server computer. However, there can be practical limitations dictated by the time it takes to back up a very large server database. Practical limits not directly related to server performance can prove to be the limiting factor on the number of users a server can support.

There is a 16-GB limitation on the size of the public and private information store databases (32 GB total), but this limitation will be removed in the next version of Microsoft Exchange Server. Presently, this limitation can become a factor on larger servers hosting many users, depending on the following factors:

  • The amount of server storage used by each client.
  • Whether client quota limitations are used and their values.
  • The degree to which single-instancing of messages and attachments increases the logical storage capacity of the server.
  • The extent to which personal folders are used, and to a lesser extent, the number of rules, views, and finders that are defined by users on the server.


Testing Methodology

To testing your methodology when determining the number of users supported by a server, you should follow the four steps below:

Optimize your server. Optimization includes optimizing the hardware and Microsoft Exchange Server Setup.

Classify your users and set expectations as to what acceptable response times they will need.

Calculate your user data and use the Load Simulator tool.

Analyze your data.

Step One: Optimizing Your Server

This section describes how to configure the hardware you are using with Microsoft Exchange Server.

Configuring Your CPU

There is not a lot you can do to optimize your CPU. However, it is important to note that Microsoft Exchange Server does not scale well past four CPUs. For example, a Windows NT® Server computer dedicated to a Microsoft Exchange Server organization with more than four CPUs does not provide a boost in performance. Those CPUs could be put to better use elsewhere. As far as the type of CPU is concerned, the faster the better. Therefore, using a Pentium 133 chip provides much more performance than a 486/66 and a little more performance than a Pentium 100.

There is one optimization step you can take with Windows NT Server that improves how your server uses its CPUs.

To optimize how your server uses its CPUs

In Control Panel, double-click the System icon.

Choose the Performance tab.

Under application performance, boost the slider bar to halfway between None and Maximum.

This boosts the system priorities that Windows NT Server places on background tasks.

Using Memory

Microsoft Exchange Server uses all the memory you can give it, up to the total size of your information store. At that point, your entire database is in memory. The minimum amount of random access memory (RAM) recommended for Microsoft Exchange Server is 24 MB, but testing has shown that having 64 to 128 MB of RAM provides much better performance than an upgraded CPU.

To maximize the memory usage of your Windows NT Server computer

In Control Panel, double-click the Network icon.

Select the Services tab, then select Server.

Select Properties, then select Maximize Throughput for Network Applications.

You can also configure virtual memory to use a larger page file. It is difficult to determine exactly how large the page file should be, but a good rule of thumb is to choose 125 MB plus the amount of physical RAM. For example, if your server has 64 MB of RAM, you can set the page file size to 189 MB (125 plus 64).


Disk I/O Subsystem

The Disk I/O subsystem is one area where much optimization can be accomplished. However, before you try to optimize the disk I/O subsystem in your computer, you should understand the following background information.

Server Transaction Logs

Microsoft Exchange Server issues I/Os to the disk subsystem on the server to read data from disk into memory or to write data out to permanent storage. For example, when a user opens his or her Inbox, the set of properties in the default folder view must be accessed for each of the first 20 messages in the Inbox folder and returned to the user. If this information is not cached in memory on the server from a recent access, it must be read from the server information store database on disk before the action is completed. The disk read I/O is synchronous to the user-initiated action.

Similarly, if a message is transferred from another server, the message must be secured to disk before the receipt of the message can be acknowledged. This prevents message loss in case of power outages.

The disk I/Os issued by Microsoft Exchange Server are either reads or writes and are either synchronous or asynchronous. Additionally, while all read I/Os and asynchronous write I/Os may be considered random, many of the synchronous writes issued by Microsoft Exchange Server are sequential. That is, a special method of writing changes to disk known as a sequential, write-ahead transaction log is used to speed up actions that require synchronous write I/O.

If the I/O to the drive is completely sequential in nature, the disk head generally does not move at all and only occasionally needs to shift over a single track. The average seek drops close to zero, dramatically increasing the number of disk I/Os per second that the drive can support.

For this reason, hosting Microsoft Exchange Server database transaction logs on a dedicated physical disk drive is critical in ensuring good disk write I/O performance. Placing the information store transaction logs on a physical disk with no other sources of disk I/O on the drive is the single most important aspect of improving Microsoft Exchange Server performance.

It is best to use the file allocation table (FAT) file system for this drive because it performs the best with sequential activity. However, note that the Windows NT file system (NTFS) must be used after this log exceeds 2 GB.

Random Disk Access I/O

Other than the transaction logs, the remaining sources of disk I/O on Microsoft Exchange Server are generally random in nature. This includes the Windows NT page file, server databases, message tracking logs, and so on. The number of disk I/Os issued by the different parts of the system will vary over time while different server components do their work. For example, when a message is received from another server and delivered to a user, the MTA first secures the message to disk in its transient database, which causes a single random write to the MTADATA directory. It then makes a call to the system attendant, which writes a log entry into the message tracking log. Finally, the MTA then notifies the information store that a message is available, at which time the information store receives a message from the MTA and writes the message into a permanent database. This generates synchronous write I/O to the information store transaction log, and asynchronous read and write I/O to the information store database in the MDBDATA directory.

Because the source of these random server disk I/Os varies, you can combine the remaining disk drives into a software or hardware stripe-set, which enables the combined capacity of all the remaining disk drives in the system to be made available to any server component that is performing I/O.

Using a Page File

You use a page file when the processes running on a Windows NT computer (including Windows NT itself) need more code and/or data pages over a period of time than there is physical memory in the computer.

If you have a lower-memory Microsoft Exchange Server computer, (for example, a computer with 24 MB and 50 to 100 users), some paging will occur on computers completing the normal set of Microsoft Exchange Server processes, such as handling user requests, moving mail off or onto a server, and so on.

Paging makes up a significant percentage of your total disk I/O because the working sets of all the Microsoft Exchange Server (and Windows NT Server) processes don't completely fit in physical memory all at once. Paging is a technique for implementing virtual memory. If the server is the only one in the site and off-server traffic is minimal, the MTA won't be doing much (except for expanding the occasional distribution list) and it will leave more room for the rest of the server processes, which results in less paging. Conversely, more paging will occur if you run additional processes on the same computer (beyond the core Microsoft Exchange Server services such as the Internet Mail Service), or if you import directory objects, generate the Offline Address Book, start up the server services, or do anything else that is non-typical.

If you have enough memory in your Microsoft Exchange Server computer such that the majority of the pages needed by all server processes fit into physical memory at the same time, you won't page very much during normal operation. Remember, however, that the working set of the information store and the directory store includes the buffer caches. Even on larger computers with 128 MB or more of RAM, you can page with very little activity if the buffer caches are set too high for the amount of RAM in the computer.

It is not recommended to dedicate a disk just to the page file because if you are paging, you will achieve better I/O performance by combining that drive into the stripe set and placing the page file there. If you aren't paging, it wastes drive space. It's best to stripe drives together to handle large databases because they are large, single files. You probably won't have many separate partitions over which to spread the page file, so placing it on the stripe set achieves the same result.


Running the Performance Optimizer

A server under load that exhibits poor response time will generally be bottlenecked on one or more of the three critical server hardware resources: CPU processing capacity, RAM, or the I/O subsystem.

Servers vary widely from low-end single processor, single-disk servers with small amounts of RAM to giant multiprocessor computers that rival the power of mainframes. Microsoft Exchange Server will run on all of them, but there are configuration settings that need to be adjusted to ensure that Microsoft Exchange Server is properly optimized for your specific server hardware.

The Microsoft Exchange Performance Optimizer automatically detects your server's hardware and adjusts configuration settings that are hardware-dependent. If you have not run the Optimizer after installing Microsoft Exchange Server on your server hardware, it will most likely perform poorly. Any time you add or remove hardware to your Microsoft Exchange Server computer, you should rerun the Optimizer to ensure that Microsoft Exchange Server is properly tuned for your hardware.


Using Load Simulator

If you are trying to determine the optimum number of users per server on your own, it is important to represent the users as accurately as possible. Some organizations have no idea how their user base will use Microsoft Exchange Server because they may have never had any messaging products on which to base their numbers. Other organizations will have some idea, based on previous experience, as to how their users will use a messaging platform. However, Microsoft Exchange Server may provide features and functionality that have never been available to their user community, so the organization may not fully understand what impact these new features can have.

For testing purposes, users are classified as having low, medium, and heavy usage. Initially, the users' states were as follows:

Parameter | Low-Usage User | Medium-Usage User | Heavy-Usage User
Number of non-default folders | 20 | 40 | 60
Number of messages per folder | 5 | 5 | 5
Number of messages in Inbox | 1 | 4 | 9
Number of messages in Deleted Items folder | 1 | 1 | 1

For testing purposes, we defined low-usage users as those who do the following on a daily basis:

  • Divide their time into an 8-hour daytime and a 4-hour nighttime.
  • Originate three new messages (that is, not replies and forwards) to four recipients, and save a copy of these messages in the Sent Mail folder.
  • Read new mail five times and old mail 12 times.

    Note Reading new mail consists of opening the Inbox and reading every piece of new mail that the user has received. Reading old mail consists of selecting one folder at random and reading one message in that folder.

Testing demonstrated that light users:

  • Used the following commands when working with messages: Reply (10 percent of the time), Reply All (3 percent), Forward (5 percent), Move (none of the time), Copy (one of the time), and Delete (40 percent).
  • Loaded 25 percent of the attachments received.
  • Limited their Inbox to 20 messages.
  • Emptied their Deleted Items folder once.
  • Made one change to their schedule.

Medium-usage users were defined as those who do the following on a daily basis:

  • Divide their day into an 8-hour daytime and a 4-hour nighttime.
  • Compose six new messages (that is, not replies and forwards) to four recipients, saving a copy of them in the Sent Mail folder.
  • Read new mail 15 times and old mail 12 times.

Testing demonstrated that medium users:

  • Used the following commands when working with messages: Reply (15 percent of the time), Reply All (5 percent), Forward (7 percent), Move (20 percent), Copy (none of the time), and Delete (40 percent).
  • Loaded 25 percent of the attachments they received.
  • Limited their Inbox to 125 messages.
  • Emptied their Deleted Items folder once.
  • Made five changes to their schedule.

Heavy-usage users were defined as those who do the following on a daily basis:

  • Divide their time into an 8-hour daytime and a 4-hour nighttime.
  • Originate eight new messages (that is, not replies and forwards) to five recipients, saving a copy of them in the Sent Mail folder.
  • Read new mail 20 times and old mail 12 times.

Testing demonstrated that heavy users:

  • Used the following commands when working with messages: Reply (20 percent), Reply All (7 percent), Forward (7 percent), Move (20 percent), Copy (none of the time), and Delete (40 percent).
  • Loaded 25% of the attachments received
  • Limited their Inbox to 250 messages.
  • Emptied their Deleted Items folder once.
  • Made 10 changes to their schedule.

The data above generated the following computed averages:

 | Light User | Medium User | Heavy User
Messages sent per day | 6.7 | 19.8 | 38.6
Messages received per day | 20.4 | 55.9 | 118.9

The message mix for these users was also varied. Four different message types/sizes were used: 1K, 2K, and 4K messages, plus a message with a 10K attachment. A mix of these messages was used for each user type and weighted as follows:

Message Size/Type | Light User | Medium User | Heavy User
1K message | 9 | 7 | 6
2K message | (none) | 2 | 2
4K message | (none) | (none) | 1
10K attachment | 1 | 1 | 1


Server Definitions

The following table lists the criteria used to define low-end, middle, and high-end servers:

Server Type | Manufacturer | Processor | RAM | Disk Config | Network
Low-End |  |  |  |  |
Server A | Gateway 2000 | 1- 486/66 | 32 MB | 1 - 515MB 1 - 1 GB | Intel EtherExpress Pro
Server B | Compaq Proliant | 1 - 486/66 | 32 MB | 1 - 1 GB 1 - 2 GB | Compaq Netflex II
Middle |  |  |  |  |
Server C | Compaq Proliant | 2 - 486/66 | 64 MB | 1 - 2 GB | Compaq Netflex II
Server D | Compaq Proliant | 1 - Pentium 90 | 64 MB | 1 - 2 GB 1 - 8 GB Stripe | Compaq Netflex II
High-End |  |  |  |  |
Server E | AT&T 3555 | 8 - Pentium 90 | 512 MB | 2 - 2 GB 1 - 24 GB Stripe 1 - 16 GB | 3COM Etherlink III


Running Load Simulator

Following are the basic steps for running Load Simulator.

To run Load Simulator

Verify that you have classified your users and set up the servers you want to test.

Install the Microsoft Exchange Client on the Windows NT Workstation computers or Windows NT Server computers you plan to use as the Load Simulator clients. (Note that Load Simulator only runs under Windows NT.)

Determine what the acceptable response time should be for your users. Usually, 1 second (1000 milliseconds) is a good criteria to use, but you may decide that 1.5 seconds (1500 milliseconds) is adequate.

Using Load Simulator, define your test topology and generate your user import files.

For each server you plan to test, use the Microsoft Exchange Server Administrator program to import those user definitions into your Microsoft Exchange Server directory.

Using Load Simulator, define the initial state of both your users and public folders.

Run the User Initialization and Public Folder Initialization tests against your server to populate the Microsoft Exchange Server information store.

Define a few tests with the user classifications that you have previously defined and run them against the server platforms. For example, you may decide you want to test 250 light users against a middle-defined server.

Each pass of Load Simulator tool runs for several hours and produces one number that is the 95-percent weighted average response time (in milliseconds) that each of the Load Simulator users experienced during that test. You can use several different user counts to generate several different data points and then graph the results.


Detecting Performance Bottlenecks

If you have a user who complains that the server is running too slowly, do you need to buy more hardware? It is important to realize that detecting performance bottlenecks is an art and that your ability to do so will improve with experience. For example, you may think that memory is your bottleneck. However, if you purchase more memory for your server, you may discover that the server still isn't performing better because the CPU is the bottleneck.

The goal is to determine which of the three major parts of the server—memory, disk I/O subsystem, or CPU—is causing the bottleneck. The Windows NT Performance Monitor tool can be an effective aid in making the correct decision.

Memory

To determine if the system requires more memory, you need to find out how much your system is paging. Use the Performance Monitor to track the following elements of the paging file: percentage usage and memory percent available. If the paging file is more than 50 percent used and if less than 25 percent of the total memory is available, then it's best to add more RAM.

Disk I/O

To determine whether the disk I/O subsystem is the bottleneck, you need to find out if the server is being I/O-bound on asynchronous I/Os to the Microsoft Exchange Server database. To determine this, review the following performance monitor counters: PhysicalDisk: Disk Queue Length and PhysicalDisk: %Disk Time.

The Disk Queue Length parameter shows how many outstanding disk requests there are per physical disk. It includes requests in service at that time. Multi-spindle disk devices can have multiple disk requests active at one time. Therefore, look for the disk queue length minus the number of spindles on the disk device. The disk is I/O-bound when the difference between the length of the queue and the number of spindles on the disk device is consistently high. According to the Windows NT Performance Monitor, this difference should average less than two.

Disk time is the percentage of elapsed time that the selected disk drive spends servicing requests. A high percentage indicates that your system is spending most of its time servicing disk requests. In this case, your system needs either faster disk drives or more disk drives over which to spread the requests.

CPU

The CPU can have a high utilization even if the disk and/or memory are causing the bottleneck. Therefore, it's best to check those two areas before checking the CPU. To determine if your system requires more processors, track System: % Total Processor and Process: % Processor - Process X. If the total system processor use is averaging more than 75 percent, you probably need to add another processor. So if you already have four CPUs and are still CPU-bound, you need to upgrade the processor type or add a second server.


Conclusion

How many users can you host on a single Microsoft Exchange Server computer?

As has been shown, this question is not simple to answer. Even the question itself must be defined before you can proceed. To answer this question, you must first define what a user or a server actually means. It is also important to remember that different organizations will generate different results that are specific to their environment.

By knowing what factors affect Microsoft Exchange Server performance, how to optimize your configuration, and what to look for when trying to detect bottlenecks, you can maintain a more efficient Microsoft Exchange Server organization.

The following section describes the different processes developed to automate the setup of Microsoft Exchange Server and Microsoft Exchange Client. Each section has a set of prerequisites as well as a defined process showing you how to complete the installation.


Updating Windows NT Server 3.51 to Service Pack 4

Windows NT Server 3.51 must already be installed on the server computer, and all users must be logged off of Windows NT Server before you update Windows NT Server 3.51 to Service Pack 4.


Procedure

Use the following procedure to update Windows NT Server version 3.51 to Service Pack 4.

To update Windows NT Server 3.51 to Service Pack 4

  • Using the built-in scheduling service in Windows NT Server, schedule the Ntsp4upd.bat file to run when no users are logged on to the server (some time at night is usually best). This batch file takes one argument—the name of the server where the installation directory resides (and from which the Windows NT Server 3.51 Service Pack 4 will be installed). An example of a typical argument might be ntsp4upd cisvr002.

    Note that the batch file uses drive X, so any previous connections made to this drive will be disconnected during the setup process.

This batch file will apply the Service Pack unattended and reboot the server.


Setup Options

After you have updated Windows NT 3.51 to Service Pack 4, you can choose from the following three possibilities to set up a new Microsoft Exchange Server computer.

  • A Microsoft Exchange Server computer that will create a new site. The batch file for this setup is Newsite.bat.
  • A Microsoft Exchange Server computer that will join an existing site, for example, a new server in an existing Microsoft Exchange site. The batch file for this setup is Newsrv.bat
  • An administrative-only computer. The batch file for this setup is Newadmin.bat. This type of setup needs to be completed for any server intended to back up Microsoft Exchange Server, and for any server that will be used as a Microsoft Exchange Server administrator console. To run this setup, you need to schedule the correct .bat file to run in the Windows NT Server scheduler.


Updating Microsoft Exchange Server 4.0 to Microsoft Exchange Server Service Pack 1

Microsoft Exchange Server 4.0 must already be installed on the server computer, and all Microsoft Exchange users must be logged off of Microsoft Exchange Server before you update Windows NT Server 4.0 to Service Pack 1.


Procedure

Use the following procedure to update Microsoft Exchange Server 4.0 to Service Pack 1.

To update Microsoft Exchange Server to Service Pack 1

  • Using the built-in scheduling service in Windows NT Server, schedule the Exsp1upd.bat file to run when no users are logged on to the server (some time overnight is usually best). This batch file takes one argument—the name of the server where the installation directory resides (and from which Microsoft Exchange Server 4.0 Service Pack 1 will be installed). An example of a typical argument might be exsp1upd cisvr002.

    Note that the batch file uses drive X, so any previous connections made to this drive will be disconnected during the setup process.

This batch file will stop all of the Microsoft Exchange Server services, apply Service Pack 1 unattended, and then restart all of the services.


Optimizing Microsoft Exchange Server Performance

Microsoft Exchange Server 4.0 must already be installed on the server computer. All Microsoft Exchange users must be logged off of Microsoft Exchange Server before this process starts.


Running the Performance Optimizer

This process has not been automated. Therefore, to complete this process, you must be logged on to the Windows NT Server computer where Microsoft Exchange Server is installed. To optimize performance, run the Microsoft Exchange Server Performance Optimizer (located in the Microsoft Exchange program group). The Performance Optimizer will stop all Microsoft Exchange Server services, and then prompt you for the following information:

How many users will this server host?

This should be the number of users located in that office.

What services will run on this server?

Select all options (Private Mailbox, Public Folders, Connector, and Multi-server. The services that should be chosen depend on the organization.

How many users will be in the entire Microsoft Exchange Server organization?

The recommended number of users is between 1,000 and 9,999 (depending on the organization).

How much memory should Microsoft Exchange Server use?

It is recommended that this remain at zero, which means that Microsoft Exchange will use all available memory. Note that this ultimately depends on the organization, as an organization might run another process on the same server.

After answering these questions, perform the following steps:

Choose Next. A window is displayed indicating that the program will run tests on the disk partitions.

After the tests are completed, choose Next. Performance Optimizer displays a window that indicates the optimal locations for the various Microsoft Exchange Server databases and transaction logs.

Choose Next to accept the defaults.

To move the file automatically, choose Next.

When the display prompts you to restart the Microsoft Exchange Server services, choose Finish.


Automated Installation of Microsoft Exchange Client

The following are procedures for installing Microsoft Exchange Client on a Windows NT workstation.


Procedure

Because Microsoft Systems Management Server (SMS) is not fully deployed at this time, it cannot be used to deploy the Microsoft Exchange Client. However, there is a simple command you can run to complete an automated installation.

To complete an automated installation of Microsoft Exchange Client

Because users cannot install this software on their local computers, you must log on to a workstation.

After you log on to the workstation, run the Instexch.bat file. This batch file takes one argument—the name of the server where the installation directory resides (and from which Microsoft Exchange Client 4.0 will be installed). An example of a typical argument might be instexch cisvr002.

Note that the batch file uses drive X, so any previous connections made to this drive will be disconnected during the setup process.

This batch file will set up the necessary Microsoft Exchange Client software onto the workstation without any interaction from the Administrator.

Creating User Profiles

Note that Microsoft Exchange Client 4.0 must already be installed on the client before you create the user profile. Also, you must run this process for every user who logs on to the workstation and wants to access his or her mail.

To create a user profile

Log on to a workstation as the user.

Run the Doprof.bat file. This batch file takes one argument—the name of the server where the installation directory resides (and from which the Microsoft Exchange Client 4.0 will be installed). An example of a typical argument might be doprof cisvr002.

Note that the batch file uses drive X, so any previous connections made to this drive will be disconnected during the setup process.

This batch file will create a Microsoft Exchange Client profile for the currently logged-on user.


Chapter 2 Working with MS Exchange Server

The following sections in this chapter can help you gain more flexibility when working with Microsoft Exchange Server:

  • Using Russian, Eastern European, Greek, and Turkish Language Character Sets
  • Message Transfer Agent (MTA) Routing
  • Fan-out
  • Moving Microsoft Exchange Server to Another Computer


Using Russian, Eastern European, Greek, and Turkish Language Character Sets

This section describes the steps needed to use the Microsoft Exchange Internet Mail Service with Russian and Eastern European character sets.


Russian and Eastern European Character Sets

Use the procedures below to work with Russian and Eastern European language character sets.

Setup

Before making any changes to the Microsoft Exchange Internet Mail Service, make sure that C_1250.nls (Eastern European Latin2) or C_1251.nls (Russian) is in your \<Windows NT Root>\System32 directory, and that the following is added to the system registry:

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control
\NLSCodepage
1250 = REG_SZ "c_1250.nls" (Latin2)
1251 = REG_SZ "c_1251.nls" (Russian)

Installation

Use the following procedures to install Russian or Eastern European character sets.

To install Russian or Eastern European character sets

  • If you want to install the Russian character set, copy the KOI8-R.trn file from the localized client software to the \Exchsrvr\Connect\Trn directory on your Microsoft Exchange Server computer;

    –or–

    If you want to install the Polish, Czech, or Hungarian character set, copy the ISO88592.trn file from the localized client software to the \Exchsrvr\Connect\Trn directory on your Microsoft Exchange Server computer.

Adding Russian or Eastern European Character Sets as a Global Option

  • To add the Russian character set as a global option, start the Microsoft Exchange Administrator program and set the "Internet Mail Character Set Translation" MIME and non-MIME to KOI8-R when using the Russian character set.
  • To add the Polish, Czech or Hungarian character sets as global options, set the "Internet Mail Character Set Translation" MIME and non-MIME to ISO 8859-2.

Specifying Message Content by E-mail Domain

If you do not want to set Russian or Eastern European character sets as global options, the message content can be specified by e-mail domain.

To specify message content by e-mail domain

In the Microsoft Exchange Server Administrator program, select a server, and then select Configuration.

Choose Connections, and then select Internet Mail Service.

Select the Internet Mail tab, and then choose E-Mail Domain.

Select a character set.

Changing the Windows NT Registry to Use the Russian Character Set

To use the Russian character set, open the Windows NT Registry Editor and add the following information:

HKEY_CLASSES_ROOT\MIME\Database
Charset
koi8-r
Codepage = REG_DWORD 0x04E3 (1251)
Codepage
1251
BodyCharset = REG_SZ "koi8-r"

Changing the Windows NT Registry to Use the Polish, Czech, or Hungarian Character Set

To use the Polish, Czech, or Hungarian character set, add these entries to the Windows NT registry:

HKEY_CLASSES_ROOT\MIME\Database
Charset
iso-8859-2
Codepage = REG_DWORD 0x04e2 (1250)
Codepage
1250
BodyCharset = REG_SZ "iso-8859-2"

To ensure that the character sets take effect, you must restart the Microsoft Exchange Internet Mail Service after making changes to Microsoft Exchange Server or the Windows NT registry.


Greek and Turkish Character Sets

If you want to use Greek or Turkish character sets with the Microsoft Exchange Server Internet Mail Service, follow the steps in the sections below before viewing one of these languages.

Note Before making any changes to the Microsoft Exchange Server Internet Mail Service, make sure that these file names are available in your Windows NT\System32 directory: C_1253.nls (Greek) or C_1254.nls (Turkish). Then make sure that the following entries are added to your system registry:

HKEY_LOCAL_MACHINE\ System\CurrentControlSet\Control\NLSCodepage
1250 = REG_SZ "c_1253.nls" (Greek)
1251 = REG_SZ "c_1254.nls" (Turkish)

Installation

Use the following procedure to install Greek and Turkish character sets.

To install Greek and Turkish character sets

  • To install Greek character sets, from your Windows NT Service Pack 3 compact disc, copy the ISO88597.trn file to the \Exchsrvr\Connect\Trn directory on your Microsoft Exchange Server computer.
  • To install Turkish character sets, from your Windows NT Service Pack 3 compact disc, copy the ISO88599.trn file to the \Exchsrvr\Connect\Trn directory on your Microsoft Exchange Server computer.

Adding Greek or Turkish Character Sets as a Global Option

  • To use the Greek character set, start the Microsoft Exchange Administrator program and set the "Internet Mail Character Set Translation" MIME and non-MIME to ISO 8859-7.
  • To use the Turkish character set, set the "Internet Mail Character Set Translation" MIME and non-MIME to ISO 8859-9.

Specifying Message Content by E-mail Domain

If you do not want to set Greek or Turkish character sets as global options, the message content can be specified by e-mail domain.

In the Microsoft Exchange Server Administrator program, select a server, and then select Configuration.

Choose Connections, and then select Internet Mail Service.

Select the Internet Mail tab, and then choose E-Mail Domain.

Select a character set.

Changing the Windows NT Registry to Use the Greek Character Set

To use the Greek character set, open the Windows NT Registry Editor and add the following information:

HKEY_CLASSES_ROOT\MIME\Database
Charset
iso-8859-7
Codepage = REG_DWORD 0x04E5 (1253)
Codepage
1253
BodyCharset = REG_SZ "iso-8859-7"

After adding these entries, restart the Microsoft Exchange Internet Mail Service.

Changing the Windows NT Registry to Use the Turkish Character Set

To use the Turkish character set, add these entries to the Windows NT Registry:

HKEY_CLASSES_ROOT\MIME\Database
Charset
iso-8859-9
Codepage = REG_DWORD 0x04e6 (1254)
Codepage
1254
BodyCharset = REG_SZ "iso-8859-9"

After adding these entries, restart the Microsoft Exchange Internet Mail Service.


Microsoft Exchange Server MTA Routing

The Microsoft Exchange Server MTA can send mail externally to:

  • Microsoft Exchange MTAs in the same site, by using remote procedure calls (RPCs).
  • Microsoft Exchange MTAs in a different site, through the Site Connector.
  • Microsoft Exchange MTAs in a different site, through the Dynamic RAS Connector.
  • Remote X.400 MTAs, through an X.400 Connector such as X.25, Transport Control Protocol/Internet Protocol (TCP/IP), or TP4.
  • Gateways such as the Microsoft Mail Connector or Internet Mail Service.

Associated with each connector is an address space (or spaces), cost, and possibly a connected site (or sites). These associations are defined by using the Microsoft Exchange Server Administrator program, and are subsequently used to generate the Gateway Routing Table (GWART). An enterprise-wide GWART is created in each site by the Routing Information Daemon (RID), which accesses local information and replicated site GWARTs to build a consolidated local GWART.

A mail message can be either a P1 message, probe, or report. Each responsible recipient of a message is routed individually. Before routing a recipient, the MTA obtains as much address information for the recipient as possible. For more information, see the "Name Resolution" section. If the recipient is local to the current MTA's address space, local routing takes place. If not, remote routing takes place. This process involves routing (through the GWART), selection, and load balancing for each recipient to obtain the routing destination.


Name Resolution

The recipient address (or O/R Name) consists of either the distinguished name (DN) or the X.400 O/R address, or both. The X.400 O/R address is logically divided into standard X.400 O/R address attributes and domain-defined attributes (DDAs). A one-off routing address is a manually entered O/R address that is not held in the directory and therefore has no DN. A valid X.400 O/R address is required for routing out of the site, even if only a DDA is specified in a one-off routing address.

Following is the name resolution process:

If the recipient address contains no DN, verify whether a DN has been saved within the DDA fields (in an earlier pass through an MTA that constructed an O/R address), and use that if it exists.

If a DN exists, read the O/R address for that DN.

Perform basic checking on any O/R address.

If the original DN was invalid or no DN exists, scan the local proxy addresses to find a match with the O/R address, and then obtain the DN. If the initial scan fails, but a common name or surname exists, perform a "fuzzy match" scan for a unique matching DN.

If the current O/R address is invalid, add the local global domain identifier (GDI) to make it valid.

When new address information for a recipient is found, the P1 recipient address is re-encoded into the message. After a message has been routed through the GWART, further name resolution may be required (for more information, see the "Remote Mailboxes" section).


Local Recipients (Mailboxes)

A recipient is considered to be local and is not routed through the GWART if a distinguished name for the recipient is available that matches the local site, and the distinguished name does not identify a custom recipient. If a recipient has only an O/R address that matches the local site O/R address space, then a distinguished name will be found by proxy search if the recipient is a valid local recipient. If no distinguished name is found, the recipient will be routed through the GWART.

Address space filtering is performed in the GWART routing routine to ensure that O/R addresses matching the local site O/R address space are not sent out of the site. If a recipient is to be routed through the GWART and matches the local O/R address space, this recipient is marked for non-delivery receipt (NDR). This option can be disabled if you use the Administrator program Share address space with other local systems option. To do so, in the Administrator window, choose a recipient, and then select the General tab. Choose Configuration, and then select Site Addressing.

If a local recipient originally had a distinguished name, and an O/R address is found by a proxy search, no re-encode of the P1 recipient address is performed because the O/R address is not required when routing locally. The exception to this is if Recipient_Disclosure is allowed, the O/R address must be included to prevent interoperability problems.


Remote Mailboxes

Any recipients who are not local and also are not DLs or custom recipients are treated as remote mailboxes. Remote mailboxes must always have a valid O/R address (a distinguished name is optional).

A valid O/R address is required to enable X.400 backbones of the message. If a distinguished name is successfully routed through the GWART, and no O/R address is available, a new address is constructed from the remote site proxy O/R address information in the connected sites.

If the new O/R address contains no DDA information, then the distinguished name is saved in the DDA of the O/R address with the special "MSXCHNGE" DDA Type to mark this O/R address as artificially constructed. This mechanism also enables encapsulation of Microsoft Exchange Server distinguished names over 1984 X.400 backbones.


Distribution List Handling

A message containing a distribution list (DL) recipient is first routed to the designated DL expansion point if the DL has a Home-MTA (or locally if none is defined). If the message is routed locally, first a DL-expansion message copy is produced by fan-out, whose recipients are the DL members. This copy is passed back through the routing process. This process is repeated recursively for each nested level of the DL. The MTA verifies that an infinite loop is not generated by DL expansion.

Each MTA can also be configured to not expand replicated remote site DLs (use the MTA Site Configuration\General tab in the Administrator program).


Custom Recipients

Custom recipients have a distinguished name that is of local significance only, therefore the distinguished name of a custom recipient is always ignored when routing the recipient through the GWART. The distinguished name and primary X.400 proxy O/R address of a custom recipient are contained in the P1 recipient address, but do not participate in routing. Instead, routing is accomplished through the Target Address attribute of the custom recipient.

Custom recipients have multiple proxy addresses of different types, but only one target address. The target address type typically matches the native mail system used to deliver mail to that custom recipient.

For routing purposes only, X.400 target addresses override the standard O/R address, and non-X.400 target addresses override the DDA portion of the O/R address. If the target address type is not X.400, it is used to route through the DDA arms of the GWART. The target address is not used to overwrite the original recipient address in the P1 of the message. If not originally specified, the target address will be created from the X.400 proxy address found by reading the distinguished name, as with mailboxes.

If no target address is found for the custom recipient, the primary X.400 proxy O/R address (if any) is used for routing.


How the MTA Is Routed

Each recipient of a message is routed individually. The MTA obtains as much address information for the recipient as possible. If the recipient is local to the current MTA's site, local routing is accomplished by using the object's Home-MTA and Home-MDB attributes.

For non-local recipients, the following routing process determines which connector a message is sent through.

  • Route Selection — Determines all of the connectors that can deliver the message.
  • Connector Selection — Determines the best connector to use from the set of available connectors.

Route Selection

The Microsoft Exchange MTA compares the recipient address to the GWART to determine the group of connectors that the message can be delivered to. The search for a match in the GWART is done in the following order:

Distinguished name (DN) — The native Microsoft Exchange address format. This is only searched if a DN for the recipient has been found. An exact match on the enterprise and site of the DN is required.

Domain-defined attribute (DDA) — The format in which custom recipient addresses are stored, for example, Microsoft Mail and simple mail transport protocol (SMTP). An exact, wildcard, or partial match on the domain-defined attribute value (DDAV) is required with an exact or partial match on the domain-defined attribute type (DDAT). Wildcard matches are used in order of the exactness of the match (that is, with the exact match first, followed by the wildcard that has the most matching characters, and so on).

O/R address — Native X.400 address type. An exact or wildcard match on the address space is required. Each field is compared hierarchically with the contents of the GWART for that field until either a match is found or it is determined that no match is present, at which point this recipient is marked for a non-delivery receipt (NDR). The hierarchy is:

  • Country
  • administrative management domain (ADMD)
  • private management domain (PRMD)
  • Organization
  • Organizational Units.

The final result of this search provides a group of connectors that can process the message.

The routing process is called from the following areas:

  • Message and probe routing
  • Distribution list expansion (route to Home-MTA and detect loops in the DL expansion tree)
  • Rerouting (all object types)
  • Report routing (normal and DL-specific)

Connector Selection

After a list of suitable connectors has been determined, the MTA needs to determine which connector is the best one to use. This determination is based on the following criteria: the final group of connectors and load balancing.

Connector Grouping

Each connector has a Max Open Retry count and an Open Retry timer configured in the DSA. Site connectors use a site-wide configurable value. If the initial attempt to open an association fails, then a timer of length Open Retry is started for the association control block (ASB) handling the original association. After the timer begins another attempt to open an association, it is processed for that ASB. This process can be repeated Max Open Retry count times for each connector. After the maximum number of retry counts has been used on all available connectors, the message will NDR for the set of recipients for which that connector is to be used. The retry count for each connector is stored on the message in question and updated during rerouting.

If the message has not been rerouted in this MTA, exclude the connector that this message came in on, to avoid immediate loop detection.

Select the group of connectors where the message retry count is less than the Max Open Retry count for the connector.

Activation schedule: X.400 Connectors and Dynamic RAS Connectors follow an activation schedule that determines how connections are scheduled to the remote system.

There are four possible settings for the activation schedule:

  • Active always
  • Selected times (according to the activation schedule)
  • Remote initiated
  • Never active

Site Connectors, the Internet Mail Service, Microsoft Mail Connectors, and other XAPI gateways are always active.

In addition to the activation schedule, for purposes of routing, there are four activation states. They are, in order of preference:

  • Active now
  • Will become active
  • Remote initiated
  • Never active

These activation states are processed in the following order:

Choose a subgroup of connectors that are active now.

If there is no match, then if any connectors will become active, find the subgroup of connectors that will become active soonest (several may become active in five minutes).

If there is no match, then if any connectors are remote initiated, choose this subgroup of connectors.

If there is no match, then use the connectors that are never active.

Choosing the Subgroup of Connectors with the Lowest Open Retry Count

Within this subgroup, connectors that are not currently retrying (waiting on an Open Retry timer) are chosen. This approach, known as preemptive rerouting, is used so that the MTA does not attempt to route a message to a connector that is known to have not connected the last time it tried.

Suppose that you have a Site Connector and a Dynamic RAS Connector with a higher cost, and the LAN is down. A message is first routed to the Site Connector because it has a lower cost. When the connection fails because the LAN is down, the message is rerouted through the Dynamic RAS Connector. Although the cost is higher, this preemptive rerouting is more likely to achieve timely delivery of the message.

Any new message that comes in before the Open Retry timer has expired on the Site Connector will skip the Site Connector and be routed to the Dynamic RAS Connector first.

Within the group that meets the previous criteria, choose a subgroup of connectors with the lowest cost.

Within the group that meets the previous criteria, choose a subgroup of local connectors over remote connectors. Site Connectors are counted as local if they are not homed on any particular server; otherwise the Site Connector has an actual locality.

If a connector is remote (as indicated by the Home-MTA attribute), it means that the connector exists on a remote MTA within this site (that is, the message will be routed to that Microsoft Exchange MTA). The MTA selects local connectors first to avoid an extra hop to the remote MTA in the site. Otherwise, no connectors exist to service this address space and the message is marked for NDR for this recipient.

If a non-optimal route (that is, a route that does not have the lowest cost) is chosen because the lowest-cost connectors are down, and the message has not yet been rerouted in the MTA, the MTA performs a virtual reroute from the lowest-cost connector to the currently selected connector. This is necessary to prevent loop detection due to circular routes. (When non-optimal routes are chosen, it is possible, and sometimes desirable, for the message to travel circular routes before reaching the final destination.) The example below illustrates why this is necessary.

A<-----Cost 1------->B<-----Cost 1----->C<-----Cost 1----->D

A<-----Cost 10----->D

A message destined for MTA D will be routed in the following order: A->B->C. However, if the C->D connector is waiting on an Open Retry or is unavailable when the message arrives at C, the MTA on C will route the message to the higher-cost alternate route: C->B->A->D.

Without the virtual reroute at MTA C, the message would be loop-detected when it reentered MTA B. In this situation, it is assumed that the incoming connector will be filtered out of the initial routing attempt for a message (otherwise MTA B would route the message directly back to C due to cost considerations).

Load Balancing

After the final group of connectors has been chosen, the MTA load balances between them. Load balancing is accomplished by randomly choosing one of the connectors in the final group (as they all have equal cost) rather than calculating current queue size, message size, and so on.

After a connector has been routed for a message recipient, it is preferentially routed again when that connector is found in a subsequent recipient's final connector group. This prevents a message for multiple recipients from being routed to the same connector group (because one message has been split into several messages). The first connector chosen from a group is used for later recipients.

If a Site Connector is selected, the Microsoft Exchange MTA load balances between target MTAs through cost-weighted randomization. However, cost 0 target MTAs are always tried first, while cost 100 target MTAs are always tried last. Cost-weighted randomization occurs only if routing to all the cost 0 target MTAs has been attempted. All administrator-designated target MTAs are tried on that Site Connector before the message is rerouted to a different connector.

Fan-out

When all recipients have been routed either locally or to a remote connector, the original message is fanned out (that is, multiple copies are created, one for each distinct message destination). Each message has the responsibility attribute set for all recipients who have been routed to that destination.

When only a few recipients for a given destination allow for message database encoding format (MDBEF) messages, the message copy for a particular destination is split into two copies. However,this situation is not typical, because conversion on the sending MTA is usually decided based on the properties of the message and the destination MTA/connector, rather than on the per recipient properties.

Conversion Decision

When the MDBEF content type is used, only one address can be included for a message originator/recipient. Although the address can be the DN address or the O/R address, it is usually the DN address. For this reason, DN access for the originator and all recipients is required during conversion. That way, the O/R addresses required by P2 can be obtained. The decision to convert from MDBEF to P2 can only be delayed until the final replicated Microsoft Exchange site (where the MTA can always obtain access to the objects) is referenced by DNs in the message. The decision to convert must be made as soon as possible, to ensure that all information required for the conversion is available.

The main conversion decision process is based on the content type of a message and the destination (either the local MTA or the recipient or remote MTA/connector). As such, it is per-message. However, even if a message is of the MDBEF content type and the chosen connector allows for this content type, an individual recipient may not allow MDBEF.

Per-recipient checking is completed during routing to verify whether a particular recipient can support MDBEF. If a recipient is a Microsoft Exchange recipient, it is assumed to support MDBEF. A recipient is assumed to be a Microsoft Exchange recipient if it supports MDBEF and if:

  • The remote MTA is a Microsoft Exchange MTA (Site Connector/Dynamic RAS Connector).
  • A DN for the recipient is known.
  • The recipient is a custom recipient or one-off, and the proxy address matches the connector's Connected Sites routing proxy.

If a recipient is not known to support MDBEF, the message is converted by the conversion decision routine during fan-out. However, the following exceptions override the per-recipient MDBEF determined during routing:

  • Inbound conversion always assumes that all recipients support MDBEF.
  • XAPI gateways always allow MDBEF.

Result Processing

The result thread receives results for a message indicating:

  • Delivery succeed/fail
  • Transfer-out succeed/fail
  • DL expansion okay
  • Routing attempt failed

If transfer-out failed, the message is rerouted. If delivery failed, an attempt is made to reassign the message (that is, alternate recipient handling will occur).

If the message is not rerouted or reassigned, checks are made to determine whether a report is required for the recipients. The report is sent only after all responsible recipients have been delivered or transferred successfully, or the MTA is unable to deliver a subset of recipients for some reason. The one exception is that a report is sent immediately for any completely invalid recipients that cannot be routed.

Rerouting and Retries

If a message fails to be sent through its chosen connector, the MTA attempts to reroute the message.

However, there are exceptions:

  • If the message is sent to a gateway, no rerouting occurs and the message is considered by the MTA to have been processed to completion.
  • If a message is routed to a never active or remote initiated connector, no rerouting occurs because association is started (unless the activation schedule is changed later).

During rerouting, only the O/R address of the first responsible recipient is used to reroute the message. This is not an optimal solution, because some message recipients may end up traveling a longer path than if they were rerouted individually. However, this reduces the code complexity and processing time required. There are no loop-detect issues, because the rerouting action resets the X.400 loop-detect algorithms.

Every connector has a retry count and a retry interval that determine how many times, and at what intervals the MTA will try to send a message through each of the connectors. The Site Connector and the Dynamic RAS Connector default to a 10-minute retry interval and a maximum count of 144 retries. On each fan-out message, a copy of the message is stored as a retry count for each connector and target MTA that has been tried.

When a message is routed to a connector that is inaccessible, the retry count for that connector is incremented on the message, and the message is immediately rerouted using the routing and selection process outlined earlier. After all connectors have been tried and the maximum retry count has been encountered, the message will NDR.

For each connector that is tried, if the openconnection fails it will (independently of the message) start an open retry timer to retry the open.

After a message is successfully rerouted, the external and internal trace information for the message is updated to indicate that a reroute has been performed.

Recipient Reassignment

Microsoft Exchange Server does not expose some X.400 alternate-recipient functions, although the Microsoft Exchange MTA supports all these functions. These functions are:

  • Recipient-assigned alternate recipient. (Recipient redirects the message to someone else.) This function, which can be disabled by setting the "Recipient_Reassignment_Prohibited" flag in the message, is supported in Microsoft Exchange Server.
  • Management domain (MD)-defined alternate recipient (or dead-letter recipient). This can be disallowed by setting the "Alternate_Recipient_Allowed" flag appropriately in the message. This is not supported in the Microsoft Exchange Server Administrator program.
  • Originator-requested alternate recipient. The originator requests an alternate recipient to be used if the message would otherwise NDR. This feature is not displayed in the Microsoft Exchange Client information store.

The redirect-and-deliver function is specific to Microsoft Exchange. If this flag is set, a copy of the message is delivered to the recipient and to the specified alternate recipient. To maintain X.400 conformance, a delivery receipt is sent only for the copy delivered to the alternate recipient.

Report Handling

Reports are internally generated in three areas:

  • Routing
  • Result processing
  • Recovery

Reports can also be received from remote systems. The routing process for reports is the same as for messages and probes, regardless of the report's origin, except when the report is destined for a DL.

When the report destination is a DL, the MTA backtracks through Originator_ and DL_Expansion_History to find the originator of the message. Each O/R name found by this recursive process in turn becomes the next report destination and is then passed back through the routing process. If the previous entry in this list was a distribution list, the process is repeated until the actual originator is found.

Loop Detection

Loop detection in Microsoft Exchange uses standard X.400 internal and external trace information. It also uses Microsoft Exchange-specific information contained in the per-domain bilateral information of a message or the additional information of a report. This information is used so that multinational enterprises can be supported without undue configuration complexity. In this way, X.400 loop detection triggering can be avoided.

External trace information documents the actions taken on a message, probe, or report by each MD that the message passes through. Each MD the message enters indicates whether the message was relayed or rerouted, plus any Other_Actions (such as redirection or DL expansion) performed by that MD. If the message enters the same MD twice without a reroute, redirection, or DL expansion, the message will be loop detected and will NDR.

Internal trace information is maintained for messages that are routed within an MD. Each MTA the message enters indicates whether the message was relayed or rerouted, plus any Other_Actions (such as redirection or DL expansion) performed by that MTA. If the message enters the same MTA twice without a reroute, redirection, or DL expansion, the message will be loop-detected and will NDR. Note that the internal trace information is removed from a message when it is transferred out of an MD.

An X.400 MD is uniquely defined by the c, a, and p components of the O/R address space. These fields are collectively termed the MD's global domain identifier (GDI). Because Microsoft Exchange uniquely identifies sites by using the c, a, p, and o components of the O/R address space, it is possible for a message to traverse a site that has the same c, a, and p values as a different site traversed earlier. This would provoke loop detection on the message in a normal X.400 system. To prevent this, each Microsoft Exchange site adds Microsoft Exchange-specific per-domain bilateral information to messages and additional information to reports. This information contains a site DN for the site being traversed.

If a loop is detected in the external trace information, the current site DN is searched for in the Microsoft Exchange-specific information. If the current site DN is not found, it is not a real loop, and therefore X.400 loop detection is suppressed.


Moving Microsoft Exchange Server to Another Computer

It may be necessary to move Microsoft Exchange Server from one computer to a new, more powerful system. This section outlines the steps required to move Microsoft Exchange Server from one computer to another.

You can move a Microsoft Exchange Server from one computer (Server A) to another computer (Server B), assuming:

  • The two computer names are unique.
  • You have Microsoft Exchange Server, Enterprise Edition or Microsoft Exchange Server, Standard Edition with the Microsoft Exchange Connector.
  • Server B is in the same Windows NT domain as Server A, or in a Windows NT domain that has full trust with the domain that contains
    Server A.


Saving Data on the Original Server (Server A)

It is important to stop all services on Server A and back up the entire Exchsrvr directory. If the logs and database files are on different drives, make sure to back these up as well, or run the Performance Optimizer and move all logs and databases to the Exchsrvr directory where Microsoft Exchange Server was installed.

If you have the Key Management server installed, make sure to back up the Security directory that was created by KM server. This directory is created by default on drive C. Note, however, that the Security directory may not be under the Exchsrvr directory. You also need to back up the KM server startup disk.

The following steps are required to back up your data on the original server.

To back up data on your server

From the Support\Sample\Csvs\Mailbox directory on the Microsoft Exchange Server compact disc, copy Mailbox.csv to the hard drive.

Change the Read-Only attribute on this file.

From the Support\Samples\csvs\Dl directory on the Microsoft Exchange Server compact disc, copy Dl.csv to the hard drive.

Change the Read-Only attribute on this file.

In the Microsoft Exchange Server Administrator window, choose Directory Export from the Tools menu.

In the Directory Export dialog box, under Export objects, select only the Mailboxes check box.

Under the Home Server list, select Server A.

Select the Include subcontainers check box, and then select Mailbox.csv as the output file.

After export, edit Mailbox.csv and change all occurrences of Server A to Server B. Save the file as Mailbox-Server B.csv.

Return to the Microsoft Exchange Administrator window, and from the Tools menu, select Directory Export.

Select only the Distribution list check box.

Under the Home Server list, select All.

Select the Include subcontainers check box, and then select Dl.csv as the output file.


Installing Microsoft Exchange on the New Server (Server B)

Make sure that Server B is in the same Windows NT domain as Server A , or in a domain that has full trust with the domain containing Server A.

Note If you are running Microsoft Exchange Server, Standard Edition without the Microsoft Exchange Connector, follow the steps in the section on moving Microsoft Exchange Server, Standard Edition (later in this chapter), instead of the steps in this section.

If Server A is a primary domain controller (PDC) and you do not plan to leave it running after moving Microsoft Exchange Server, install Windows NT on Server B and make Server B a backup domain controller (BDC) in the same Windows NT domain as Server A.

Install Microsoft Exchange on Server B, joining the Microsoft Exchange site of Server A. Install all the connectors that were installed on Server A.

If you are running Microsoft Exchange Server, Standard Edition on Server A, you must install the Microsoft Exchange Connector on Server A before attempting to add Server B to the existing site.

Upgrade Server B to the same Microsoft Exchange Service Pack as Server A.

All users on Server A should appear in the global address list (GAL) for
Server B.

In the Administrator window, double-click Server B, and then select the Public Information Store.

Choose Properties from the File menu, and then select the Instances tab (this tab is not included in Microsoft Exchange Server, Standard Edition). All of the public folders on Server A should appear.

Under the Public folders list, select all folders, and then choose Add to add all the public folders to the local information store on Server B.

By default, the first server in a site will contain and be responsible for the site folders. Site folders consist of the offline Address Book folder, the Microsoft Schedule+ Free/Busy Information folder, and the Organizational Forms folder, if one exists. Other servers installed in the site rely, by default, on the first server for this information. Therefore, if Server A was the first server to be installed in the site, make sure that you have added instances of the Organization Forms, Schedule+ Free/Busy Information, and offline Address Bookfolders to the public information store on Server B.

This step ensures that all folders in the site are replicated to Server B. After all steps for moving Server A to Server B are completed, individual public folders can be removed from the public information store on Server B if there are other replicas of these folders on other servers in the same Microsoft Exchange Server site.

In the Administrator window, choose a server, and then choose a site.

Select Public Information Store, then select Public Folder Resources.

Change the Public Folder Server setting to Server B.

In the Administrator window, choose Configuration.

Double-click DS Site Configuration.

Select the Offline Address Book tab.

Under the Offline Address Book server list, select Server B.

In the Administrator window, choose Configuration.

Double-click Site Addressing.

Select the General tab.

Under the Routing calculation server list, select Server B.

Note that the Apply button is not enabled when you select Server B from the Routing calculation server list. To enable this button and ensure that the change to the routing calculation server setting is recorded, in the Display Name box, add and then remove a character.

For each DL defined, select the Distribution List tab and verify that the expansion server is not set to Server A.


Moving Mailboxes to the New Server

This section describes how to move all the mailboxes on Server A to Server B.

Note You can move mailboxes to another server in a site by choosing Move Mailbox from the Tools menu in the Microsoft Exchange Server Administrator program. However, this only enables you to move the mailboxes to the Recipients container. If this is acceptable, then using the Move Mailbox command is the easiest way to move mailboxes.

To keep the mailboxes in the same containers or subcontainers as they were on Server A

Stop the Information Store service on Server B. In Control Panel, double-click the Services icon. Under the Service list, select Microsoft Exchange Information Store, and then choose Stop.

In the Exchsrvr\Mdbdata directory on Server B, create a subdirectory called Bak.

Move all files from the Exchsrvr\Mbddata directory in Server B to the Bak directory.

Copy the Pub.edb file from the Bak directory to the Mbddata directory.

Before proceeding to the next step, make sure that you completed a backup of the Exchsrvr directory on Server A. This backup should be completed after all services are stopped. Also, verify that you have successfully created the Mailbox-ServerB.csv file.

Start all of the Microsoft Exchange services on Server A.


Deleting Mailboxes from the Original Server

Follow the procedure below to delete mailboxes from Server A.

To delete mailboxes

In the Administrator window for Server A, choose Server Recipients.

From the menu bar, choose View, and then choose Mailboxes.

Choose Columns, and then add Home Server to the Show the following columns list.

Move the position of the Home Server entry so that it is the second entry in the list.

Select each container that includes Microsoft Exchange mailboxes.

Delete all users who have Server A as their home server.

Recreating Mailboxes on the New Server

Before recreating mailboxes on Server B, make sure that the Microsoft Exchange Directory service is running on Server B.

To re-create mailboxes

In the Administrator window for Server B, select Server B.

In the right pane, double-click Directory Service.

Choose Update Now.

Select Refresh all items in the directory, and then choose OK.

This causes all changes made to the directory on Server A to be replicated to Server B. Note that after the replication is completed, the mailboxes that were deleted from Server A should not be displayed on Server B.

In the Administrator window, choose Directory Import from the Tools menu.

Choose Import File, and then select the Mailbox-ServerB.csv file.

Make sure that the server displayed in the MS Exchange Server box is
Server B.

Under Account creation, select Use select container if it is not specified in the file. Do not select the Create Windows NT account check box.

Choose Import.

Repeat this step for each file that contains mailbox information. All mailboxes that were originally on Server A should now be re-created on Server B.


Restoring All User Messages on the New Server

Before following the procedure outlined below, make sure that the Microsoft Exchange Directory service is running and that the Microsoft Exchange Information Store service is not running on Server B.

To restore user messages on the new server

Copy the Priv.edb file from the Mdbdata directory of the Server A backup to the Mdbdata directory on Server B.

Now you should have two files in the Mdbdata directory of Server B: the Privd.edb file that was copied from the Server A backup and the Pub.edb file that was in the Mdbdata directory on Server B.

Do not copy Pub.edb from the Server A backup. There should be no .log or .chk files in the Mdbdata directory of Server B.

At the command prompt, switch to the Exchsrver\Bin directory.

Type ISINTEG -Patch.

In Control Panel, double-click the Services icon, and then start the Microsoft Exchange Information Store service on Server B.

In the Administrator window, select Server B.

From the File menu, choose Properties.

Select the Advanced tab, select the All Inconsistencies option, and then choose Adjust.

All mailboxes should now be migrated to Server B. As long as the Microsoft Exchange Directory service is running on Server A, all users should be able to log on to the Microsoft Exchange Client by using their old profiles. Even though the profiles point to Server A, the Microsoft Exchange Directory service on Server A automatically redirects the client to Server B and the profile is modified to point to Server B.


Recreating DLs on the New Server

You only need to re-create DLs if you have manually moved the mailboxes to Server B. This is because the process of manually moving the mailboxes involved deleting the users on Server A. When you did this, the users were removed from the DLs. This is also the reason why all the DLs were exported.

To re-create the DLs

In the Administrator window, choose Directory Import from the Tools menu.

Select the Dl.csv files, and then choose Import.


Moving the KM Server

The following steps are applicable only if you already have the KM server running on Server A and security is enabled for the Microsoft Exchange mailboxes on Server A.

To move the KM server

Remove the KM server from Server A.

In Control Panel, double-click Services, and then stop the Key Management Server service on Server A.

In the Exchkm directory on the Microsoft Exchange Server compact disc, run Setup.exe.

Install the KM server on Server B. Select the option to create a startup disk.

After the installation is completed, stop the Key Management Server service on Server B.

From the KM Server Startup disk for Server A, copy the Kmspwd.ini file onto another disk for Server B. Label this disk "KM Server Startup Disk: Server B."

From the backup of the Security directory on Server A, copy the Security\Mgrent directory to the Security directory of Server B.

Insert the new KM Server Startup disk for Server B (labeled "KM Server Startup Disk: Server B") into the disk drive on Server B.

On Server B, start the Key Management Server service.

As long as the .epf files are still on your users' computers and their profiles have not changed, your users can read all previously encrypted mail.


Moving the Microsoft Mail Connector

The following steps are applicable if you have the Microsoft Mail Connector installed on Server A.

To move the Microsoft Mail Connector

Run the Microsoft Exchange Administrator program for Server A, noting the settings for the Microsoft Mail Connector.

On Server A, stop the Microsoft Mail Connector Interchange, any Microsoft Mail PCMTA services, and the Directory Synchronization service.

Make sure that the Microsoft Mail Connector is installed on Server B. If it isn't, install it.

On Server B, configure the Microsoft Mail Connector exactly as it was configured on Server A.


Moving the Directory Synchronization Configuration

The following procedure describes how to move the directory synchronization configuration to the new server.

To move the directory synchronization configuration

In the Administrator window for Server B, choose Directory Replication, then double-click on the connector to display the properties for the Directory Synchronization Server object.

Change the Server setting to Server B. When you do so, the following warning message appears:

"Changing the server in Responsible DXA can cause the loss of Directory Synchronization information. A full export of Directory Synchronization information will occur in the next scheduled cycle."

Choose OK to dismiss the warning, and then choose OK again to close the tab.

Run the Microsoft Mail Administrator program for each Microsoft Mail requester postoffice. Select Config, DirSync, Requestor, Export, then Import.

On Server B, start the Microsoft Mail Connector Interchange service, any Microsoft Mail PCMTA services, and the Directory Synchronization service.

At the next scheduled time, Microsoft Mail and Microsoft Exchange will be resynchronized.


Moving the Directory Synchronization Requester

In the Administrator window for Server B, right-click the Directory Synchronization Requester object to display its properties.

Change the Server setting to Server B. When you do so, the following warning message appears:

"Changing the server in Responsible DXA can cause the loss of Directory Synchronization information. A full export of Directory Synchronization information will occur on the new Responsible DXA in the next scheduled cycle."

Choose OK to dismiss the warning, and then choose OK again.

Select the Requester tab, select Full Export, and then select Import on the Next Cycle.


Moving X.400 Connectors

Follow the steps below if you have one or more X.400 Connectors installed on Server A.

To move X.400 Connectors

On Server B, install the required MTA transport stacks.

On Server B, display the properties for each X.400 Connector.

Change the MTA transport stack so that it is a stack installed on Server B.

On Server A, delete the MTA transport stacks.

On Server B, request a full directory update.

On the directory service object under Configuration, Servers, Server B, choose Update Now, and then select Refresh all items in the directory.


Moving Directory Replication Connectors

Follow the steps below if you want to move directory replication connects.

To move directory replication connectors

On Server B, display the properties of each directory replication connector.

Change the local bridgehead server to Server B, if it is currently Server A. Note that you may need to change the remote bridgehead settings on the remote directory replication connector, if the remote server is not available on the network.


Moving the Internet Mail Service

Reconfigure each Internet Mail Service on Server B.


Moving Third-Party Connectors

Reinstall all third-party connectors installed on Server A.


Microsoft Exchange Client Profiles

Make sure that both Server A and Server B are running. Server A should be kept running until every client has logged on at least once. This ensures that the Microsoft Exchange Client profiles are automatically redirected to Server B instead of Server A, thus eliminating the need to manually modify client profiles.

After all clients have logged on to Microsoft Exchange Server at least once, use the steps below to remove Server A from the organization. If Server A is removed before all clients have logged on, the profile on the clients will need to be modified to point to Server B.


Removing the Original Server from the Organization

Use the procedure below to remove Server A from the organization.

To remove Server A

In the Administrator window for Server A, select Public Information Store.

From the File menu, choose Properties.

Select the Instances tab.

Remove all public folder instances from this store.

On Server A, run the Microsoft Exchange Server Setup program, and then remove the installed connectors.

Run the Microsoft Exchange Administrator program in raw mode.

From the View menu, choose All.

Select the Recipients container. In the right pane, select Microsoft Schedule+ Free/Busy Connector.

From the File menu, choose Raw Properties.

Change every occurrence from Server A to Server B to include the computer name, display name, home MDB, and home MTA. Note that you must choose Set to ensure that these changes will take effect.

In the Administrator window for Server B, select Server A, and then press the delete key. When you do so, a warning message appears stating that there is still one mailbox and gateway on Server A. This warning refers to the system attendant mailbox on Server A, which can be safely deleted.

Choose Yes. When you do so, another warning appears:

"The contents of all public folder instances on this server will be deleted. Are you sure you want to delete server 'Server A'?"

Choose Yes.

Server A will be deleted from the Microsoft Exchange Directory on Server B, and all data has been moved from Server A to Server B.


Moving Microsoft Exchange Server, Standard Edition

With Microsoft Exchange Server, Standard Edition, it is not possible to have more than one server in a site or to connect Microsoft Exchange Server sites. To move Microsoft Exchange Server from one server computer (Server A) to another (Server B), follow the procedures described in this section.

Install the Microsoft Exchange Connector on Server A. Note that this software must be purchased separately.

Follow the steps outlined earlier in this chapter.

If it is not possible to use the Microsoft Exchange Connector, follow the steps below to move Microsoft Exchange Server from Server A to Server B. After the move from Server A to Server B, all Microsoft Exchange Clients will need their profiles modified to point from Server B to Server A.


Backing Up Data

Before moving Server A to Server B, follow the steps below to back up your data on Server A.

To back up Microsoft Exchange Server data

Stop all Microsoft Exchange Server services on Server A and back up the entire Exchsrv subdirectory. If the logs and database files are on different drives, back up these directories as well.

If the KM server is installed, back up the Security directory.

From the KM Server Startup disk, back up the Kmpswd.ini file.

Start all Microsoft Exchange services on Server A.


Exporting Mailboxes, Custom Recipients, and DLs

To export mailboxes, custom recipients and distribution lists, follow the steps below.

From the Support\Samples\Csvs\Mailbox directory on the Microsoft Exchange Server compact disc, copy the Mailbox.csv file to your computer.

From the Support\Samples\Csvs\Custom directory on the same compact disc, copy the Custom.csv file to your computer.

From the Support\Samples\Csvs\Dl directory on the same compact disc, copy the Dl.csv file to your computer.

For each of these three files:

In Windows NT Explorer, from the File menu, choose Properties, and then clear the Read-Only check box.

To export the Mailbox.csv file

In the Administrator window for Server A, choose Directory Export from the Tools menu.

Choose Export File, and then select Mailbox.csv.

Choose Container, and then select the Recipients container.

Under Export objects, select the Mailbox check box.

Choose Export.

Edit the Mailbox.csv file, replacing all instances of Server A with Server B.

Save the file.

Repeat these steps for each top-level container. Use different file names for each top-level container and do not specify Mailbox.csv as a file.

To export the Custom.csv file

In the Administrator window, choose Directory Export from the Tools menu.

Choose Export File, and then select Custom.csv.

Choose Container, and then select the Global Address List container.

Under Export objects, select the Custom Recipient check box.

Choose Export.

To export the Dl.csv file

In the Administrator window, choose Directory Export from the Tools menu.

Choose Export File, and then select Dl.csv.

Choose Container, and then select the Global Address List container.

Under Export objects, select the Distribution list check box.

Choose Export.


Saving Directory Synchronization Configuration Information

If you are using the Microsoft Mail Connector and have directory synchronization set up with Microsoft Mail postoffices, follow the steps below to save directory synchronization configuration information.

To save directory synchronization information

  • If Microsoft Exchange is the dirsync server, note the names of the dirsync server and each remote requester. Also note the Import and Export containers for each remote requester.
  • If Microsoft Exchange is a dirsync requester, then note the exact name of the requester and the Import/Export containers.

This information must be available when recreating the directory synchronization objects on the new server. You need to re-create the dirsync server and requester exactly as they were defined on Server A to preserve DLs containing Microsoft Mail custom recipients that were previously dirsync'd into Microsoft Exchange Server. The custom recipients need to be re-created in the same container, with the same directory name and DN. This is only possible by importing the exported custom recipient data from the old server. By importing the custom recipient and DL information, you will retrieve all the old custom recipients and DLs.

However, if the dirsync requesters (or remote requesters) were not created with identical names, the Microsoft Mail custom recipients will not be associated with the new requesters. These custom recipients will never be deleted automatically as part of directory synchronization, even if the user has been deleted from the Microsoft Mail postoffice. To maintain the old directory synchronization information, the dirsync requester's server must have the same names, and must create new custom recipients in the same container.

You cannot just copy over the Exchsrvr directory from Server A to Server B, because the Microsoft Exchange directory file (Dir.edb) contains the name of the server. Because the computer names of the source (Server A) and target
(Server B) computers are different, you cannot use the Dir.edb file from Server A on Server B. Due to this restriction, all information in the Microsoft Exchange directory must be re-created on Server B.


Saving Public Folders

Follow the procedure below to save your public folders.

To save public folders

Log on to the Microsoft Exchange Client by using an account on Server A that has at least Read access to all public folders. If necessary, use the Administrator program to grant this access permission on public folders.

Add "Personal Folders" to the current profile using PublicFoldersOnServerA.pst as the file name.

Create a new personal folder called "Public Folders on Server A."

Select all public folders and copy them to the Public Folders on Server A folder that you just created. This should also copy any forms associated with the public folders.


Saving Organizational Forms

If you have organization-wide forms, follow the procedure below.

To save your organizational forms

While still in the Microsoft Exchange Client, create a new personal folder called "OrgForms."

Select the new folder.

From the File menu, choose Properties.

Select the Forms tab.

Choose Set, and then select Organization Forms. This is the name of the folder that was specified using the Microsoft Exchange Administrator program (under Tools\Forms Administrator).

Select all the forms listed in the list on the left, and with all the forms highlighted, choose Copy. This copies all the selected forms to the list on the right. All the forms in the list are then copied to the OrgForms personal folder that you created in step one.

Repeat these steps for each forms library.

As mentioned earlier, you cannot copy the Pub.edb file from Server A to Server B and expect all the public folders to be available on Server B. After you copy Pub.edb to Server B, and run the ISINTEG troubleshooting utility and the DS/IS consistency adjuster, the public folders on Server A will still not be available on Server B. Only after you display the public information store properties on Server B, select the Instances tab and add all the public folders to be homed on Server B, will these folders be available.

Note The Instances tab is not available with Microsoft Exchange Server, Standard Edition. Because Standard Edition servers are stand-alone servers, they do not have the ability to store replicas of public folders.


Installing Microsoft Exchange Server

On Server B, install Microsoft Exchange Server with the same organization and site names as the Microsoft Exchange installation on Server A. Also, you must install any Service Packs that were installed on Server A.


Installing the KM Server

Follow the procedure below to install the KM server:

To install the KM server

If you were using the KM server on Server A, install the KM server on Server B. Select the option to create a startup disk. After the installation is completed, stop the Key Management service on Server B.

From the KM Server Startup disk for Server A, copy the Kmspwd.ini file to another disk for Server B. Label this disk "KM Server Startup Disk: Server B."

On the new server, rename the Security\Mgrent subdirectory to Mgrent.original.

From the backup of the Security directory on Server A, copy the Security\Mgrent directory to the Security directory of Server B.

Insert the new KM Server Startup disk for Server B (labeled "KM Server Startup Disk: Server B") into the disk drive on Server B.

Start the Key Management Server service on Server B.


Re-creating Mailboxes, Custom Recipients, and DLs

Follow the procedure below to re-create your mailbox, custom recipients, and distribution list files.

To re-create mailboxes, custom recipients, and DLs

Start the Microsoft Exchange Administrator program for Server B.

Recreate the same containers as you did for Server A.

From the Tools menu, choose Directory Import.

Import the Mailbox.csv file, and any other files that were previously created.

Import the Custom.csv file.

Import the file DL.csv file.

All the mailboxes, custom recipients, and DLs from Server A should now be
re-created on Server B.


Restoring User Messages

Follow the procedure below to restore user messages:

To restore user messages

On Server B, make sure that the Microsoft Exchange Directory service is running and that the Microsoft Exchange Information Store service is not running.

On Server B, rename the Mdbdata subdirectory under the Exchsrvr directory to Mdbdata.original.

On Server B, create a new directory called Mdbdata under the Exchsrvr directory.

Copy the Pub.edb file from the Mdbdata.original directory to the Mdbdata directory.

At this stage, the Mdbdata directory should contain only the Pub.edb file.

From the Mdbdata directory of the backup of Server A, copy the Priv.edb file to the Mdbdata directory of Server B.

Now you should have two files in the Mdbdata directory of Server B: the Priv.edb file that was copied from the Server A backup and the Pub.edb file that was in the Mdbdata directory of Server B.

Note Do not copy the Pub.edb file from the Server A backup.

There should be no .log or .chk files in the Mdbdata directory of Server B.

At the command prompt, switch to the Exchsrvr\bin directory, and type the following command to run the ISINTEG troubleshooting utility:

ISINTEG -patch

On Server B, start the Microsoft Exchange Information Store service.

In the Administrator window for Server B, select Server B.

From the File menu, choose Properties.

Select the Advanced tab.

Select All inconsistencies, and then choose Adjust.


Restoring Organizational Forms

Follow the procedure below to restore your organizational forms.

To restore your organizational forms

In the Administrator window of Server B, choose Forms Administrator from the Tools menu.

Choose New. If your Forms Library is called "Organization Forms," accept the default value in the Library folder name box; otherwise, type the correct library name.

After you have selected the correct library name, choose OK, and then choose Close to close the Organization Forms Library Administrator dialog box.

If you have more than one forms library, repeat steps two and three to re-create each library.

In the left pane of the Administrator window, select Folders, System Folders, EFORMS REGISTRY.

In the right pane, select the forms library that you created in steps two and three. The default name should be "Organization Forms."

From the File menu, choose Properties.

Select the General tab, and then choose Client Permissions.

Add your Microsoft Exchange mailbox with the Owner role.

Close all open dialog boxes.

Repeat steps for each forms library that you created.

Quit the Administrator program.

Log on to the Microsoft Exchange Client against Server B.

Add the Personal Folders Information service to the client profile. Select the PublicFoldersOnServerA.pst file that you created earlier. This .pst file should contain two folders: "Public Folders on Server A" and "OrgForms," the forms library that you created.

In the Microsoft Exchange Client Viewer, select the OrgForms folder.

From the File menu, choose Properties.

Select the Forms tab, and then choose Manage.

Choose Set, and then select all the forms displayed in the list on the right.

Choose Copy.

All the forms should now be copied from the .pst file to the server-based Organization Forms folder and should be available to users.


Restoring Public Folders

Use the following procedure to restore your public folders

To restore public folders

Make sure that you are logged on to the Microsoft Exchange Client.

Select the Public Folders on Server A folder.

The folder contents list (right pane of Microsoft Exchange Server) should contain all the subfolders under the Public Folders on Server A folder. Select all of these subfolders and copy them to the All Public Folders folder.


Reconfiguring Directory Synchronization

If you are using the Microsoft Mail Connector to communicate with Microsoft Mail postoffices, you need to reconfigure the Microsoft Mail Connector on Server B exactly as it was on Server A.


Microsoft Exchange as the Directory Synchronization Server

If Microsoft Exchange was the dirsync server on Server A, reconfigure Server B to be the dirsync server. Use the same settings as on Server A, including the name. Reconfigure all remote dirsync requesters exactly as they were on Server A. Make sure that the requester names and Import/Export containers are all the same.

Start the Microsoft Mail Administrator program for each Microsoft Mail requester postoffice, and then select Configuration, Dirsync, Requestor, Export and Import.

On Server B, start the Microsoft Mail Connector Interchange service, any Microsoft Mail PCMTA services, and the Directory Synchronization service.

At the next scheduled time, the Microsoft Mail and Microsoft Exchange Server should be resynchronized again.


Reconfiguring Microsoft Exchange Server as a Dirsync Requester

If Microsoft Exchange was a dirsync requester on Server A, reconfigure Server B to be a dirsync requester with the same settings as Server A.

To reconfigure Microsoft Exchange Server as a dirsync requester

Select the Requester tab.

Choose Settings, and then select Full Export and Full Import.


Regenerating the Offline Address Book

The offline Address Book will not be migrated automatically to Server B. It must be reconfigured and regenerated on Server B.

To regenerate the offline Address Book on Server B

Verify that Microsoft Exchange Server is running.

In the Administrator window, choose Configuration.

Double-click DS Site Configuration.

Select the Offline Address Book tab.

Select the correct container, and then choose Generate Offline Address Book Now.


Schedule+ Free/Busy Data

The Schedule+ Free/Busy information cannot be migrated to Server B. However, this information is regenerated automatically when users make changes to their calendars.


Moving Third-Party Connectors

All third-party connectors installed on Server A must be reinstalled on Server B.


Microsoft Exchange Client Profiles

All Microsoft Exchange Client profiles must be modified to point to Server A rather than Server B.

To modify the client profile

In Control Panel, double-click the Mail icon, and then choose Show Profiles.

Select the profile to be modified, and then choose Properties.

Select Microsoft Exchange Server from the list of information services, and then choose Properties.

Change the Microsoft Exchange Server name to Server B.

Note After a profile is modified, offline folder files (.ost) files are not accessible. Normally, a copy of all information in the .ost file is saved in the user's private mailbox on the server . If mail in the .ost file must be saved, before modifying the profile or connecting to the old server, the user must run the Microsoft Exchange Client in offline mode, and then copy all required messages and/or folders to a .pst file. If the user tries to connect to the old server or modifies the profile with the new server name, the .ost file will not be accessible. For security reasons, it is not possible to recover data from an ost file.


Moving Details Templates

Use the procedure below to move details templates.

To move details templates

On Server A, create a directory called Templates.

From the Support\Samples\Tpl directory on the Microsoft Exchange Server compact disc, copy Tpl.ini and Tpl.csv to your Templates directory on Server A.

Remove the Read-Only attributes from these files.

Edit the Tpl.ini file. Under the [Import] and [Export] sections, modify the Basepoint entry by replacing the words "ORG" and "SITE" with your organization and site names. Save the file.

At the command prompt, switch to the Templates directory and type the following:

C:\Exchsrvr\BIN\ADMIN /e tpl.csv /d Server A /o tpl.ini

Copy the Templates directory from Server A to Server B.

On Server B, at the command prompt, type the following:

C:\Exchsrvr\BIN\ADMIN /i tpl.csv /d Server B /o tpl.ini.


If Both Computers Have the Same Name

Follow the procedures below if you are moving Microsoft Exchange Server from one computer to another computer that has the same name.

The steps in this section apply if the new Microsoft Exchange Server computer is in:

  • The same Windows NT domain as the Microsoft Exchange Server computer to be moved; or
  • A domain that has a two-way trust relationship with the Windows NT domain that contains the Microsoft Exchange Server computer to be moved.

Verifying That a Domain Controller Is Available

Before moving Microsoft Exchange Server to the new computer, verify that the computer to be replaced is not the only Windows NT domain controller in the domain. After this computer is brought down as part of the procedure to move Microsoft Exchange Server, there must another domain controller that can validate Windows NT logon requests.


Moving a Primary Domain Controller Computer

If Microsoft Exchange Server is being moved from a primary domain controller (PDC) computer, make sure there is at least one other backup domain controller (BDC) in the Windows NT domain. After bringing down the computer to be moved, upgrade the BDC to become a PDC.


Moving a BDC Computer

If the computer to be moved is a BDC, make sure that the PDC in the domain is running and operational, or at a minimum, that there are other BDC computers that can be upgraded to become the PDC.


Moving Microsoft Exchange Server to Another Computer with the Same Hardware Platform

The steps below describe how to move Microsoft Exchange Server to a new computer that has the same hardware platform as the original computer. For purposes of this example, the two computers will be referred to as the Original Server and the New Server, even though both computers have the same NetBIOS computer name.

To back up information from the Original Server

Start the Microsoft Exchange Administrator program on the Original Server. Make note of the organization and site names.

On the Original Server, stop all Microsoft Exchange Server services.

Copy the entire Exchsrvr directory to another computer on the network, or to a tape drive. If the Microsoft Exchange Server log and database directories are on different drives, use the Performance Optimizer or the Microsoft Exchange Administrator program to move all the directories to their corresponding locations under the Exchsrvr directory where Microsoft Exchange was installed. This should be done before backing up the Exchsrvr directory.

If the KM Server is installed, stop the Key Management Server service and back up the Security directory. Back up the KM Server Service Startup disk as well.

Shut down the Original Server. As mentioned earlier, make sure that there is an operational domain controller in the Windows NT domain.

Installing Windows NT and Microsoft Exchange Server on the New Server

Use the following procedure to install Windows NT and Microsoft Exchange Server on the New Server. Before you install Windows NT on the New Server, make sure that the Original Server has been turned off.

To install Windows NT and Microsoft Exchanger Server

Install Windows NT on the New Server with the same computer name as the Original Server. If necessary, make it a BDC.

On the New Server, at the command prompt, type Setup /R to install Microsoft Exchange Server.

Use the same organization and site names that were used on the Original Server. Also, make sure to install all connectors that were installed on the Original Server. To do so, select the Custom installation option.

During setup, when prompted for the Microsoft Exchange service account, select the same service account that you used for the Original Server. This must be done because if a new service account is selected after the directory from the Original Server is restored over the New Server, the new service account will not have permissions on the directory.

Do not run the Performance Optimizer at the end of the Setup program.

Make sure that no Microsoft Exchange Server services are running.

Re-creating Data from the Original Microsoft Exchange Server on the New Server

Use the following procedure to re-create data on the New Server.

To re-create data

From the backed-up Exchsrvr directory on the Original Server, copy all the files over the Exchsrvr directory on the New Server.

Note If the Original Server and the New Server do not have the same hardware platform, do not copy the contents of the entire Exchsrver directory over the New Server. If you do so, you will destroy your executable files. For more information on how to re-create data on a new server that does not have the same hardware platform, see the "Moving Microsoft Exchange Server to Another Computer with a Different Hardware Platform" section.

Start the Microsoft Exchange System Attendant and Microsoft Exchange Directory services.

At the Windows NT command prompt, type the following to run the ISINTEG troubleshooting utility:

ISINTEG -patch

Start the Microsoft Exchange Server Information Store service.

In the Administrator window, select the New Server.

From the File menu, choose Properties.

Select the Advanced tab, select All Inconsistencies, and then choose Adjust.

Installing the KM Server

Follow the procedure below to install the KM server:

To install the KM server

If you were using the KM server on the Original Server, install the KM server on the New Server.

Select the option to create a startup disk. After the installation is completed, stop the Key Management Server service on the New Server.

From the KM Server Startup disk for the Original Server, copy the Kmsp.ini file to another disk. Label this disk "KM Server Startup Disk: New Server."

On the New Server, rename the \Mgrent subdirectory under the Security directory to Mgrent.original.

From the backup of the Security directory on the Original Server, copy the Security\Mgrent directory to the Security directory of the New Server.

Insert the new KM Server Startup disk for the New Server (labeled "KM Server Startup Disk: New Server") into the disk drive on the New Server.

Start the Key Management Server service on the New Server.

Run the Performance Optimizer to make the appropriate changes.

Start all the Microsoft Exchange Server services.

Connectors

Restore all Site Connector and X.400 Connector information on the New Server. Any Microsoft Mail, Internet Mail Service, or Dynamic RAS Connectors must be reconfigured. If you use third-party connectors, those also need to be reconfigured.

Microsoft Exchange Client Profiles

Microsoft Exchange Server should now be running on the New Server in the same way it was on the Original Server. Microsoft Exchange clients should be able to connect to the New Server in the same way as they connected to the Original Server.


Moving Microsoft Exchange Server to Another Computer with a Different Hardware Platform

Follow the steps outlined in the "Moving Microsoft Exchange Server to Another Computer with the Same Hardware Platform" section. However, rather than copying the entire Exchsrvr directory from the Original Server to the New Server, do the following.

From your backed-up copy of the Exchsrvr directory of the Original Server, copy the following subdirectories to the Exchsrvr directory on the New Server: Dsadata, Dxadata, Imcdata, Mdbdata, and Mtadata. If you overwrote all the files from the Exchsrvr directory of the Original Server, you would destroy your executable files.


Chapter 3 Optimizing Performance

Your system's performance is also affected by the server's software and hardware configurations. You can minimize performance bottlenecks by balancing server hardware resources to support the expected load and adjusting software settings. This chapter suggests ways you can maximize the number of users supported while keeping response times low. Keep in mind that if you are supporting a live user population, you must be more cautious with the changes you make.

For information about troubleshooting performance, see Chapter 7, "Troubleshooting Microsoft Exchange Server." For more information about optimizing performance, see the Microsoft Exchange Server Concepts and Planning Guide.


Performance Tuning Microsoft Exchange Server

To performance tune Microsoft Exchange Server, you need to define how your system is used. There are different configuration recommendations depending on the role of your server. For example, does your server support user mailboxes? Or does it serve as a messaging hub or mail gateway?

It is always a good idea to try to understand the workload being placed on the system by asking this question: What are your users doing? To gather user profile information, you can use the StorStat tool, which is available in the Exchange directory on the Microsoft BackOffice Resource Kit, Part Two compact disc. This tool can help greatly by providing you with sizing information.

Ultimately, you must examine the behavior of the system while it is in operation. You can do so by using the Windows NT Performance Monitor (PerfMon) tool. For more information on this tool, see the Windows NT Resource Kit. Performance Monitor enables you to observe important factors that affect the server's behavior, such as workloads (How many messages per second are arriving?) and resource demands (How much CPU time is being used? How much memory?). The information is presented as performance counters, which you can monitor in real time or collect in .log files for later analysis. When you examine the demand on resources, you can generally see what needs to be done to improve response times or throughputs.

You can use the Microsoft Exchange Server Load Simulator (Loadsim.exe) to conduct system sizing experiments prior to deployment. Load Simulator emulates a large number of client computers and places a very realistic load on the server so that you can see how it behaves and what response times to expect. Although this section does not describe the Load Simulator tool in detail, if you are conducting a Load Simulator experiment, the information provided here will help you.

Run the Performance Optimizer (PerfWiz) after you install Microsoft Exchange Server and any time you make configuration changes on the server. The Performance Optimizer is available on the Microsoft Exchange Server compact disc. The Performance Optimizer optimally adjusts a number of system settings for any hardware in the server.


Server Roles

This section discusses roles a server might fill in your messaging topology. For each role, general recommendations have been made. These recommendations are based on the assumption that you want to deploy a server with the highest possible capacity. If you don't need to "max out" the server, you may not need to follow some of these recommendations.

Servers That Primarily Support Users

The following areas are discussed to help you improve performance on servers that are primarily supporting users.

  • The disk subsystem
  • CPU subsystem
  • Memory and network capacity
The disk subsystem

In the most common customer configurations, the disk subsystem and memory are the first resources to become saturated in a Microsoft Exchange Server computer. One significant thing you can do to improve disk performance is to get the information store log files on to their own physical disks, apart from other files in the system. Because the logs are always sequentially written, having dedicated disks means that the disk heads won't be randomized by other activities. They will always be in the right place for the next write. And because seeking is the slowest thing a disk does, this is a big help.

The information store database files, on the other hand, are randomly accessed. In this case, the best thing you can do is to put the disks in a RAID array for maximum random access performance.

You can improve performance by using good disk controllers. Caching controllers increases your disk's performance for reading, and if the controller has battery backups, this can improve write performance as well. If the controller works as a write cache (or caches writes) then it must be battery backed up. Problems with cache writes (for example, in the event of a power outage) will cause the computer to lose data. Batteries are on the card to keep data on the card backed up. If the data is cached and there is a power outage, the data will be saved, not lost. Make sure that you don't put so many disks on one controller that the controller becomes a bottleneck.

It is important to consider the reliability of these disks, because your users will be depending on them. It may be wise to mirror the log files, and to use RAID 5 on the database.

Recommendations

  • Use the fastest possible disks for the information store log and database.
  • Use dedicated disks for information store logs.
  • Stripe the information store database.
  • Use a sufficient number of high-performance controllers.
CPU subsystem

After disks and memory, the next most likely resource to become saturated is the CPU.

Use the fastest possible CPUs. If the server supports only users and does not run connectors and other processes, there are limits to how much work you can offload by adding CPUs. If the server performs other processing functions, there is a definite benefit to adding more processors. For example, it may be useful to add processors if your server supports connectors or doubles as a messaging hub, domain controller, or SQL Server database.

To make the best use of your processors, use a large L2 cache. This keeps the processor from waiting while data is retrieved from main memory. Also, in a multiprocessor server, the cache keeps load off the system bus, which improves your overall throughput.

Recommendations

  • Use the fastest available CPUs.
  • Use multiprocessor-ready computers.
  • Use the largest available caches.
Optimizing memory and network capacity

Two other resources that can be saturated are memory and network capacity. If the system is thrashing (that is, if there is excessive paging), it will be obvious. If it's not thrashing, you will not notice paging at all. Not enough memory in the system will cause the system to thrash. Fortunately, it is easy to add memory to correct this.

If there is not enough network capacity (bandwidth) between the users and the server, your efforts to provide a responsive server will be unsuccessful. The network will be your bottleneck.

When local area network (LAN) connectivity is used, you have the option to replace a 10 MB Ethernet with 100 MB.

In a wide area network (WAN) scenario, there are two important things to note. First, this type of traffic is very bursty (characterized by large bursts of activity). It is not unusual to see peak usage several times the average. Second, bandwidth demand varies widely from company to company and site to site. You may see wide range characteristics of per usage bandwith utilization, depending on the usage patterns. It is typical for server-to-client traffic to be three to four times the client-to-server traffic, because the server responses to client requests are bigger than the requests themselves.

Recommendations

  • Ensure adequate memory. If your system is paging excessively, it is a good indication that you need more memory in the computer. You can fix thrashing by adding more memory or removing the load on the server.
  • Ensure adequate network bandwidth.

Servers That Support Connectors

The following tasks create additional work for a server:

  • Connecting sites by using the Site Connector, X.400 Connector or Internet Mail Service.
  • Connecting to other types of messaging systems (by using the Internet Mail Service, X.400 Connector, Microsoft Exchange Connector for Lotus cc:Mail, and so on).
  • Supporting protocols requiring content conversion such as post office protocol version 3 (POP3), network news transfer protocol (NNTP), or hypertext transfer protocol (HTTP).

The message transfer agent (MTA), for example, will be involved when connectors are used. The MTA secures all messages to disk, so if there is a lot of traffic, disk input and output can become important. One option is to provide a separate disk for MTA files; another is to maintain the MTA files in the stripe set with the information store database. The same is true for the Internet Mail Service because it also secures messages to disk.

Make sure that you have adequate network bandwidth to carry the traffic. Connector traffic will often be carried over WAN links, and as mentioned earlier, the traffic patterns can vary widely from company to company. Use the Network Monitor to verify that you have capacity available on the links.

Most connectors require the system to send and receive messages in a format that is different from the storage format. Mapping content from the storage format into another format or protocol is a CPU-intensive task that may benefit from more processors.

Recommendations

  • Use a separate disk for MTA queues, or place them in a stripe set with the information store database.
  • Use a separate disk for Internet Mail Service queues, or place them in a stripe set with the information store database.
  • Ensure adequate bandwidth between sites.
  • Consider adding more processors.

Public Folder Servers

The usage patterns for public folders vary from company to company. Some don't use public folders, others support discussion groups and news in public folders, and others deploy intensive workflow applications. If your organization supports large-scale public folder activity, keep in mind that the public information store is a separate database from the private information store. It has its own database file. This means that you can maintain the public information store database files on a logical drive that is separate from the private information database, for maximum random I/O performance. Likewise, you can maintain the public store database on a separate drive, although this is less likely to increase performance if you already have a stripe set for the database. The 16 GB limit on the private and public stores are separate, so the public store space isn't counted against the 16 GB limit of the private store, and vice versa.

Many site administrators may want to provide Internet newsgroups or Usenet, and store this data in public folders for uniform user access. In such a case, the incoming news may generate a large amount of write activity in the public store, so be sure to optimize the log drives.

Although the public and private stores are separate databases, a single instance of the database engine runs both. They share the same memory buffers. If your organization experiences heavy use of public folders, you can improve performance by splitting the public folders onto separate servers. This reduces contention for computer resources, including buffers. A pool of public folder servers can also provide flexibility in load balancing.

Recommendations

  • Understand your usage pattern.
  • If there is a large amount of read activity, focus on information store public database disks.
  • If there is a large amount of write activity, focus on information store public log disks.
  • Consider using a pool of public folder servers.

Servers That Support Other Loads

If your organization supports Microsoft Exchange Server in combination with other applications such as SQL Server, or if you use file and print services or domain controllers, you must benchmark the workload and configuration you expect to run. This is the only reliable way to determine the system performance under the expected load. Load Simulator is available to emulate the Microsoft Exchange Server part of the workload.


Introduction to Bottlenecks

This section discusses the concept of a bottleneck. The term "bottleneck" is used in various ways by many people. The precise definition that will be used here enables you to take appropriate action if a bottleneck is a problem on your server.

What Is a Bottleneck?

The bottleneck in a system is the service center with the highest demand. Demand is the number of visits to a service center multiplied by the average time taken for each visit. For example, if a workload is causing 100 disk accesses per second and the disk accesses takes 1 millisecond, then the demand for the disk is 100 milliseconds per second, or 10 percent. Following are concepts to keep in mind when analyzing bottlenecks.

  • A service center is a resource in the system that tasks must wait for when the resource is servicing another task. The CPU, disks, controllers, and network are all examples of service centers. There can also be logical resources such as locks or critical sections in software. Memory is not a resource that a task waits for. If there is not enough memory, the system starts paging. Memory cannot be a bottleneck in itself. Rather, a shortage of memory can cause the disk subsystem to become a bottleneck.
  • All bottlenecks are observed in the context of a workload. When a server is fulfilling a file-server role, its disks may be the source of the bottleneck. When the same server is acting as a domain controller, its CPU may be the bottleneck.
  • For any combination of server and workload, there is a bottleneck. Usually the bottleneck resource is not overloaded in normal operation. When it is, a queue will build up in front of that resource and service times will climb. When this occurs, the source of the bottleneck must be relieved.
  • There are two ways to relieve a bottleneck: You can decrease the visit rate to the resource (for example, by adding disks and spreading the load over them, thus decreasing the visit rate on each disk), or you can decrease the visit time, (for example, by installing faster disk drives on your computer). Keep in mind that one way to reduce the visit rate is to decrease the workload on the system, for example by moving some users to another server.

The figure below shows a characteristic respone time curve that all multiuser server share. As the load on the server increases, usage of the bottleneck resource comes closer to saturation (100 percent utilization) more of the time. As it does, there is more queuing in front of the resource and this causes response times to increase. As the resource nears 100 percent utilization, response times grow rapidly.

A server supporting happy users is not operating with its resources very close to saturation. There is some "elbow room" for the bottleneck resource, and the system operates in the part of the response curve that is below the acceptable response time limit. When the system is operating above that line, it's time to relieve the bottleneck.

What Can Be Done About Bottlenecks?

When the server appears to have slow response times, you may install a faster processor without realizing that the disk subsystem is the actual bottleneck. In this case, you can improve response times somewhat because the disk is faster. However, the capacity of the system does not change; the bottleneck is the same.

The next figure illustrates what happens if you fail to identify the bottleneck correctly or if you improve the wrong resource. The capacity of the system does not change at all. At load levels approaching saturation of the bottleneck, users do not experience improved response times.

The figure below illustrates what happens when the bottleneck is correctly identified and relieved. Again, this is accomplished by decreasing the number of visits to the device or decreasing the time per visit. Not only are response times improved at light loads, but the saturation point moves farther out. Users experience acceptable response times at higher load levels. When you review this figure, note that there is a new bottleneck in the system, but hopefully the capacity is high enough to provide acceptable performance. If not, the new bottleneck must be found and resolved.

Impact of Memory and Cache

The server's memory and L2 cache (processor cache) generally cannot become bottlenecks. This is because they are not service centers; that is, processes don't wait for these resources. If there is insufficient memory in the system, it starts paging. This increases the visit rate on the disk, and the disk becomes the bottleneck. This is commonly known as disk thrashing. When you investigate a disk bottleneck, you must also examine the paging rate. For a Microsoft Exchange Server computer, if the paging rate is more than 100 pages per second, consider adding memory. Although memory isn't technically the bottleneck, adding memory can solve the problem by relieving the disk.

An inadequate L2 cache can cause the processors to stall while waiting for data from main memory. Excessive cache misses can cause the system bus to become a bottleneck. This is commonly known as bus thrashing, and is an element to watch for, especially in multiprocessor systems. If you believe this is happening in your server, you can install the Pentium counters available in the Windows NT Resource Kit compact disc and monitor bus utilization by using the Performance Monitor.


How to Monitor a Server

One of the most important elements of performance tuning is to maintain Performance Monitor logs. If you don't record this information, you will have nothing to work with. You can set these logs to record only every two or five minutes; this is sufficient for most performance tuning work and doesn't require too much storage space.

There are three major areas to watch when you are monitoring a server with live users.

Trends in submitted loads

Observe whether your users are sending more messages now than they did a few months ago, or whether the average message size is increasing. These factors will change the load on the server, and if you are not aware of them, the load can slowly increase until you have a response-time problem. Microsoft Exchange Server provides counters that give an indication of the overall workload.

Service times

If you monitor a server alone, it is nearly impossible to calculate the overall response times that users will experience. However, you can observe the server components of the response time, and get a general idea of whether slow server response times are becoming an issue. Microsoft Exchange Server provides counters that indicate server response times.

Resource use

By observing the utilization of various resources, you can see where the bottleneck in a system is and even get an idea of where the next bottleneck might occur, after relieving the current one.

The following sections describe the counters of most interest to an administrator, performance analyst, or capacity planner when performing system tuning.

Watching for Trends in the Load

These counters don't provide a complete picture of the load on your Microsoft Exchange Server computer, but they will indicate trends over time if you track them.

Object | Counter | Description
MSExchangeIS | User Count | The number of connected client sessions.
 | Active User Count | The number of users who have been active in the last 10 minutes.
MSExchangeIS Private | Messages Submitted/min | The rate of messages being submitted to the private information store.
 | Message Recipients Delivered/min | The rate of messages being delivered by the private information store. This will be higher than the submission rate because many messages have multiple recipients.
MSExchangeIS Public | Messages Submitted/min | The rate of messages being submitted to the public information store.
 | Message Recipients Delivered/min | The rate of messages being delivered by the public information store. This will be higher than the submission rate because many messages have multiple recipients.
MSExchangeMTA | Messages/sec | The rate at which the MTA is processing messages.
 | Messages Bytes/sec | The number of bytes in the messages being processed by the MTA. Divide this by the Messages/sec counter, and you can determine the average message size.

Watching Service Times

These counters don't provide a complete picture of the responsiveness of your Microsoft Exchange Server computer, but they will indicate trends over time if you track them.

Object | Counter | Description
MSExchangeIS Private | Send Queue Size | Indicates whether the information store is keeping up with the submitted load. The queue can be non-zero at peak traffic times, but it shouldn't stay there long after the peak has passed.
 | Average Time for Delivery | Indicates how long it takes the information store to deliver messages.
MSExchangeIS Public | Send Queue Size | Indicates whether the information store is keeping up with the submitted load. The queue can be non-zero at peak traffic times, but it shouldn't stay there long after the peak has passed.
 | Average Time for Delivery | Indicates how long it takes the information store to deliver messages.
MSExchangeMTA | Work Queue Length | Indicates whether the MTA is keeping up with the submitted load. The queue can be non-zero at peak traffic times, but it shouldn't stay there long after the peak has passed.

Processor Utilization

Windows NT provides additional counters that can help you analyze processor usage, but many are more useful to a developer than to an administrator. The following counters are relevant to bottleneck analysis.

Object | Counter
System | % Total Processor Time
Process | % Processor Time

If you observe processor utilization at a fine granularity, for example every one or five seconds, note that the counters fluctuate rapidly and will frequently hit 100 percent for short periods of time. For this reason, monitoring processor usage is more useful when averaged over a longer period of time. If you are monitoring for longer periods of time and you find that the processor usage reaches 100 percent and stays there for minutes or hours, your users are probably becoming impatient with response times. You may want to size your system for around 60 percent or 70 percent processor utilization during peak times, so that there is extra room for unexpected demands and for growth.

When you are running other services in addition to Microsoft Exchange Server on the server computer, it is recommended that you analyze per-process processor usage. This enables you to determine which services are using most of the CPU time, and how to appropriately balance the load.

If the processor is your bottleneck, consider taking the following actions:

Recommendations

  • Use a faster processor or multiple processors.
  • Use a larger L2 cache. This can improve processor efficiency.

Disk Counters

There are two sets of disk counters: LogicalDisk and PhysicalDisk. Either are fine to use, but LogicalDisk makes it easier to track drive usage. In either case, you must enable the disk counters. They are turned off by default, due to the small performance hit they create.

To enable Performance Monitor disk counters

  • At the command prompt, type diskperf -y. The counters take effect after the next reboot.

Following are important disk counters:

Object | Counter
LogicalDisk | Disk Bytes Written/sec
 | Disk Bytes Read/sec
 | Disk Reads/sec
 | Disk Writes/sec
 | Avg. Disk Queue Length
 | % Disk Time (general indicator only; not a reliable indicator of disk saturation).

Compare the disk operations per second with the specifications for sustained operations provided by your vendor. If your disk operations per second are getting close to the vendor's specifications, you're nearing capacity. Note that the % Disk Time counter is not a fair indication of disk saturation. A disk that is busy 100 percent of the time may actually be capable of doing much more work, due to smart disk controllers and scheduling methods such as elevator algorithms.

Recommendations

If the disk subsystem is your bottleneck, consider taking the following actions:

  • Use the fastest possible disks for the information store log and database.
  • Use dedicated disks for the information store log.
  • Stripe the information store database disks.
  • Mirror the information store log; use RAID 5 on the information store database.
  • Use high-performance controllers, and make sure that there are enough of them for your disks.
  • Use a separate disk for MTA queues, or place these queues in the stripe set with the information store database.
  • Use a separate disk for Internet Mail Service queues, or place these queues in the stripe set with the information store database.

Information Store Disk Demands

Object | Counter
MSExchangeDB | Buffer Asynchronous Reads/sec
 | Buffer Asynchronous Writes/sec
 | Buffer Synchronous Reads/sec
 | Buffer Synchronous Writes/sec

Check the amount of disk activity generated by the information store. If you add up the read/write counters shown above, you can determine how much of the disk's activity on your information store database drive is due to the information store, and how much is generated by other services that might share the same drive.

Memory

Following are important memory counters:

Object | Counter
Memory | Pages/sec
 | Page Faults/sec
 | Available Bytes
 | Committed Bytes
Process | Page Faults/sec
 | Working Set

The Pages/sec counter indicates the rate at which pages are physically read or written on the paging drive. This indicates the contribution that paging makes to the demand for the disk.

The Page Faults/sec counter indicates the rate at which pages are faulted into the working sets of processes. Due to the page pool in the virtual memory system, the number of pages actually being read and written to disk is much less than the number of page faults. The page faults are of interest if you have services in addition to Microsoft Exchange Server running. In such a case, you can examine the rate of page faults on a per-process basis and determine where they are occurring. With this information, you can make application-tuning changes. For example, you might consider (carefully) adjusting the tradeoff between the information store buffer pool and the system memory pool. Also, by checking the per-process working sets, you can see identify the major memory allocations.

Recommendation

  • If your paging rate is over a small amount, for example 100 pages/sec, consider adding memory.

The Available Bytes counter indicates how much physical memory is available at any given time. The system adjusts working sets of processes to keep this above a certain threshold, generally 4 MB. If this level is approached, you should see higher paging and page fault rates. The Committed Bytes counter indicates the amount of virtual address space that the system has committed to applications. This must be backed by the paging file on the disk, so make sure that there is space in the paging file.

Recommendation

  • Anticipate memory issues by tracking trends in available and committed memory.

Buffers

Following are important buffer counters.

Object | Counter
MSExchangeDB | % Buffer Cache Hit
 | Buffer Asynchronous Reads/sec
 | Buffer Asynchronous Writes/sec
 | Buffer Synchronous Reads/sec
 | Buffer Synchronous Writes/sec

Depending on your usage patterns, you may be able optimize the use of server memory by adjusting the number of information store buffers. Monitor the % Buffer Cache Hit counter. If it is consistently very close to 100 percent, try decreasing the number of buffers. You should also monitor the information store disk activity. If the activity doesn't increase, your setting is correct. However, if you notice that the cache hit rate is less than 95 percent, try increasing the number of buffers. As long as the paging activity does not increase, the setting is correct. Be careful when making these changes! Make small adjustments and monitor the results until you're confident in the changes made.

Recommendations

  • Consider adjusting your information store buffer usage if the cache hit rate is very high or low.
  • If you cannot find a happy medium for this setting, you probably need to add more memory.

To change the number of information store buffers

At the command prompt, type PerfWiz -V.

Change the setting number for the information store buffers, but be careful when doing this. Make small adjustments and monitor the results until you are confident with the changes made.

The Network Interface object can be obtained by installing the Windows NT Resource Kit. If your network connection is a point-to-point link, the counters below will show all traffic on the link. If the connection is a LAN, these counters will show the traffic to and from the server being monitored.

Object | Counter
Network Interface | Bytes Received/sec
 | Bytes Sent/sec
 | Packets Received/sec
 | Packets Sent/sec

If you know the capacity ratings of your network and network interface card (NIC), you can compare these ratings to the values for the counters shown above and determine how close to capacity you are operating. For a more complete overview of network traffic, you can also use the Network Monitor tool available with Microsoft Systems Management Server (SMS). Note that Network Monitor is a stand-alone tool. You do not need to have other SMS components installed to run it.

If you find that the server is operating at or near network capacity, you can upgrade the network speed, for example, by moving from a 10-MB Ethernet to a 100-MB Ethernet, or moving from a 64-KB line to a T1 line. You may also want to consider using multiple Ethernet connections for the server, or multiple 64-KB lines, rather than one faster connection or line.

Recommendation

  • Consider faster links, multiple interfaces, and multiple links.

System Bus

If you suspect that bus saturation is an issue that affects your server, you can monitor its activity on Pentium and Pentium Pro servers. Use the p5ctrs from the Windows NT Resource Kit. To view Pentium counters, you must run Pperf and then change the configuration.

Following are important bus counters:

Object | Counter
Pentium | Bus Utilization (clks)/sec
 | % Code Cache Misses
 | % Data Cache Misses

If your system bus is near saturation, you have two options:

  • If there are many cache misses, you can use larger CPU caches; or
  • You can split the load onto multiple servers. Start by offloading any non-Microsoft Exchange Server services, if they are being used.

Recommendations

  • Use larger L2 caches.
  • Consider multiple servers.


Chapter 4 MS Exchange Server Disaster Recovery

This chapter describes techniques that can be used for Microsoft Exchange Server disaster recovery planning. For quick answers to many frequently asked questions, see the "Disaster Recovery Frequently Asked Questions" section.

Before reading this chapter, read Chapter 15 of the Microsoft Exchange Server Administrator's Guide. Although Microsoft Exchange Server is a robust and stable messaging platform, it is essential that you have a working plan to restore Microsoft Exchange Server computers and data in a timely way if a system crash or another disaster occurs. By reading this chapter, you can minimize downtime for your organization and provide the quickest possible data recovery. However, it is important that you do not take this information for granted. Instead, test, formulate, and certify your own disaster recovery plans.

Because Microsoft Exchange uses Windows NT® security for authentication, you must also consider Windows NT operating system backup and restoration procedures, as well as procedures for Microsoft Exchange Server backup and restoration. Due to this relationship, Microsoft Exchange Server disaster recovery cannot be considered independently from Windows NT disaster recovery.

An enhanced version of the Windows NT Ntbackup.exe program is available on the Microsoft Exchange Server compact disc. One of the benefits of Microsoft Exchange Server and the new Ntbackup.exe program is that they provide live backup of the Microsoft Exchange information store and directory without causing interruption to the messaging system. Ntbackup.exe also provides file-based backup services that back up the Windows NT registry.

The following figure shows the updated Ntbackup.exe program with Microsoft Exchange Server extensions.

Microsoft Exchange Server does not need to be taken offline to perform backup. The entire information store, directory, message transfer agent (MTA), and system attendant remain in service during online backup. Although the information store and directory can be backed up online, files in directories being accessed by other Microsoft Exchange Server for Windows NT services, such as the DX or PCMTA services [Microsoft Mail Connector (Appletalk) MTA], should be backed up when the respective service is not running. You can automate and schedule this backup by using the Winat.exe graphical user interface (GUI) scheduler. For more information, see the Windows NT Resource Kit. An example of a batch file that shuts down and restarts Microsoft Exchange Server services is also discussed in this chapter. This batch file can be used for other purposes as well.


Defining Data to Back Up

Two types of data must be backed up: user data and configuration data. Microsoft Exchange Server user data is stored in the public information store and the private information store (Pub.edb, Priv.edb), personal folder files (.psts), offline folder files (.osts), personal address books (.pabs), and transaction logs. Microsoft Exchange Server configuration data is stored in the Microsoft Exchange Server directory (Dir.edb), the Windows NT registry, and in various subdirectories in the Microsoft Exchange Server installation path (and potentially in paths created after you run the Microsoft Exchange Performance Optimizer). Depending on the type of backup and restoration required, these data points must be considered in your procedures.

The Microsoft Exchange Server database files are located in the directories listed in the table below. Although the default path of Exchsrvr is used in this table, you can change the location of the database files at the time of installation. To place the transaction logs on a separate physical disk from the information store and directory files, run the Microsoft Exchange Server Performance Optimizer. You can also reconfigure the paths for all database files by using the Database Paths tab for the server object.

Data | Path Name
Private information store | Exchsrvr\Mdbdata\Priv.edb
Public information store | Exchsrvr\Mdbdata\Pub.edb
Directory | Exchsrvr\Dsadata\Dir.edb
Information store transaction logs | Exchsrvr\Mdbdata\*.log


Backing Up .Pst, .Ost, and .Pab Files

The .pst, .ost, and .pab files are specific to each user within a Microsoft Exchange Server organization. Below are descriptions for each file type and suggestions for using and storing these files. For more information on data recovery procedures specific to each of these file types, see the ".Pst, .Ost, and .Pab Recovery" section.

.Pst Files

If users store .pst files on their local drives, and local drives are not being backed up, you cannot restore these files. If .pst files are stored on a file server, you need to include them in your backup routine. You can restore a .pst, and then add it to an existing user profile. If a user has password protected his or her .pst file and then forgets the password, you cannot recover the password or the data in that file. Make sure that your users are aware of this. You can repair a damaged .pst file, however, by running the Inbox Repair Tool (Scanpst.exe). For more information, see the "Using the Inbox Repair Tool to Repair .Pst and .Ost Files" section.

.Ost Files

Data in .ost files is at risk when changes have been made to the local .ost file and have not yet been replicated to the server-based store. If a user's computer fails, a new .ost file can be created on the replacement computer and all server-based information can be sent to the .ost file through synchronization. You can repair a damaged .ost file by running the Inbox Repair Tool. For more information, see the "Using the Inbox Repair Tool to Repair .Pst and .Ost Files" section.

.Pab Files

Personal address book files can be stored on a server directory or locally. Because most servers are backed up regularly at night, any server-based .pab files are also backed up. A .pab file may be lost when a user stores it locally and do not arrange for a backup. If the .pab entries must be replaced, this can cost an employee many hours of work and lost productivity.


Archiving and AutoArchiving Data with Microsoft Outlook

You can use Microsoft Outlook™ to archive data into .pst files automatically. If you plan to use this feature, make sure that you consider archive data files when planning backup strategies.

Your Outlook mailbox grows when items are created in the same way that papers pile up on your desk. In the paper-based world, you can occasionally shuffle through all your documents and archive important but not frequently used files. Documents that are less important, such as newspapers and magazines, you can discard.

When working in Outlook, you can transfer old items to a storage file manually by choosing Archive from the File menu, or you can transfer or delete old items automatically by using the AutoArchive feature. Items are considered old when they reach the age you specify.

Note Outlook can archive only files that are stored in a mail folder, such as an attached Microsoft Excel spreadsheet or Microsoft Word document. A file that is not stored in a mail folder cannot be archived.

To start AutoArchive

Running AutoArchive is a simple two-step process.

In Microsoft Outlook, from the Tools menu, choose Options.

Select AutoArchive.

Setting AutoArchive Properties

You must set the AutoArchive properties for each folder you want archived. You can also choose when to archive these folders. Individual folders, groups of folders, or all Outlook folders can be archived automatically. The process runs automatically whenever you start Outlook. AutoArchive checks the date of the items you specify and moves old items to your archive file. Items in the Deleted Items folder are not moved to another folder. They are deleted.

Several Outlook folders are created after you select AutoArchive. These folders and their default aging periods (the default time by which an item is considered old) are as follows:

  • Calendar (six months)
  • Tasks (six months)
  • Journal (six months)
  • Sent Items (two months)
  • Deleted Items (two months)

Note that AutoArchive does not archive the Inbox, Notes, and Contacts folders automatically.

Exporting and Archiving

There is a difference between exporting and archiving. When you archive, the original items are copied to the archive file and then removed from the current folder. When you export, the original items are copied to the export file but are not removed from the current folder. In addition, you can only archive to one file type, a personal folder file, but you can export to many file types such as text.

When you archive, your existing folder structure is maintained in your new archive file. If there is a parent folder above the folder you choose to archive, the parent folder is created in the archive file, but items within the parent folder are not archived in the archive file. In this way, an identical folder structure exists between the archive file and your mailbox. Folders are left in place after being archived, even if they are empty.


Backup Types

To help you establish a backup strategy, this section reviews backup types and provides a better understanding of online and offline backups.

Online Backups Versus Offline Backups

Microsoft Exchange Server online backups require that the respective service (information store or directory) is running. These backups do not disrupt messaging on Microsoft Exchange Server computers. Note that you can back up the directory service without the information store running. You can also include the Windows NT registry in the backup job.

An offline backup is a file-based backup. Unlike online backups, offline backups require that all Microsoft Exchange Server services be stopped. After you stop these services, you can run the Windows NT NTbackup program to back up all files on the desired drives.

Online Backup Types

An online backup is comprised of the following four types of backups:

Normal (Full)

In a normal backup, the entire information store and directory databases are backed up. Transaction logs are backed up and then purged. Incremental and differential backups are given context as a result of the transaction logs being purged.

Copy

A copy backup is similar to a full backup, except there is no context marking. The context for the incremental and differential backups does not get changed. Log files are not deleted. A copy backup is analogous to taking a snapshot of the databases at a given point in time without impacting other backup routines. You can use a copy backup to reproduce a particular scenario in a test environment.

Incremental

In an incremental backup, only a subset of the information store and/or directory is backed up. Only changes since the last full or incremental backup (whichever was most recent), are written to tape. Only the .log files are written to tape. These files are then purged. The purging of transaction logs sets the context for the next backup job.

For a typical incremental backup, a tape of the last full backup is required, as well as tapes for each incremental restore up to the point when the system experienced an outage. For example, a full backup can be performed on Sunday evening, while incremental backups are performed on a daily basis from Monday through Friday. If an outage occurs on Friday morning, a full backup can be performed and each incremental backup tape can be restored through Thursday. Services should not be started until the final incremental tape has been restored. Note that an incremental backup is disabled when circular logging is enabled.

Differential

A differential backup backs up the changes in the information store and/or directory since the last full (normal) or incremental backup. However, most administrators do not mix differential and incremental backups in a series. Only .log files are backed up, but they are not purged from disk. For example, if a transaction log and database restore are required, only two tapes are required for the differential backup. The two required tapes would be the latest full backup and the latest differential backup. Note that differential backup is disabled when circular logging is enabled.

If the transaction logs are intact since the last full backup, only the last full backup tape is required. This is because the restore process plays back all logs from the point of the last full backup to the current Edb.log file, thus restoring all transactions to date.

Caution When restoring data, make sure that you do not select Erase existing data; otherwise, you'll erase the log files to date.


Log Files and Circular Logging

Although transparent to the end user, Microsoft Exchange Server maintains several database files or stores. The information store consists of two databases: the private information store (Priv.edb) and public information store (Pub.edb). The Microsoft Exchange Server directory is stored in the Dir.edb file. The respective Microsoft Exchange Server services use transaction log files for each of these databases. The information store service manages both the public and private information store databases.

Microsoft Exchange Server implements log files to accept, track, and maintain data. All message transactions are written first to log files and memory, and then to their respective database files. This is done to optimize performance and recoverability.

Because log files are written to sequentially and Microsoft Exchange Server writes message transactions to log files immediately, Microsoft Exchange Clients experience a high level of performance. Log files are always appended to the end of the file. However, Microsoft Exchange Server database files are written to randomly.

To optimize recoverability, log files can be used to recover message transaction data if a hardware failure corrupts the information store or directory database files, provided you have backed up the logs or the logs are intact. Log files are typically maintained on a separate physical disk drive from the information store and directory database files.

If database files are damaged, a backup can be restored and any data that has not been backed up but has been recorded in the transaction logs, can be played back. These transactions are entered into the restored database file to bring the database up-to-date.

The directory and information store services use the following logs and files:

  • Transaction logs
  • Previous logs
  • Checkpoint files
  • Reserved logs
  • Patch files

Transaction Logs

Transaction logs can be kept on a separate physical drive from that of their respective .edb files. By default, information store logs are maintained in the Exchsrvr\Mdbdata directory and directory service logs are maintained in Exchsrvr\Dsadata.

Each subdirectory contains an Edb.log file, which is the current transaction log file for the respective service. Both the information store subdirectory and the directory service subdirectories maintain a separate Edb.log file. Log files should always be 5,242,880 bytes in size. If log files are not this size, they are probably damaged.

Because transactions are first written to the Edb.log files and then written to the database, the current actual or effective database is a combination of the uncommitted transactions in the transaction log file, which also reside in memory, and the actual .edb database file.

When the Edb.log files are filled with transaction data, they are renamed and a new Edb.log file is created. Note that .log files are always 5 MB, regardless of how many transactions have been recorded in them.

Previous Logs

When an Edb.log is renamed, the renamed log files are stored in the same subdirectory as the Edb.log file. The log files are named in a sequential numbering order (for example, Edb00014.log, Edb00015.log, and so on). Note that hexadecimal numbers are used.

Previously committed log files are purged by the Windows NT Ntbackup.exe program during an online normal (full) backup or an online incremental backup. However, not all previous log files are purged. After every 5 MB of transactions are written, a new log is created, but not necessarily committed. There may be several previous .log files that aren't committed that will not be purged.

When circular logging is enabled, a history of previous .log files is not maintained and therefore these .log files are not purged by backup operations. In fact, incremental and differential online backups are not permitted when circular logging is enabled. Note that transactions in log files are committed to the respective .edb file when the service is shut down normally. For example, when the information store service experiences a normal shutdown (that is, the service shuts down with no errors), any transactions that existed in log files and not in Priv.Edb and/or Pub.Edb files are committed to the .edb files. Note that .log files should not be manually purged while services are running. In general, it is best to purge logs by using the backup process.

Checkpoint Files

Checkpoint files are used for recovering data from transaction logs into .edb files. The checkpoint is the place marker within the Edb.chk file that indicates which transactions have been committed. Separate Edb.chk files are maintained by the information store and directory services. Whenever data is written to an .edb file from the transaction log, the Edb.chk file is updated with information specifying that the transaction was successfully committed to the respective .edb file.

During the data recovery process, Microsoft Exchange Server determines which transactions have not yet been committed to the respective .edb file by reading the Edb.chk file or by reading the transaction log files directly. Note that the Edb.chk file is not required.

The information store and directory service each reads its Edb.chk file during startup. Any transactions that have not been committed are restored into the .edb files from transaction logs. For example, if a Microsoft Exchange Server computer experiences an outage, and transactions have been recorded into the transaction log but not yet to the actual database file, Microsoft Exchange Server attempts to recover this data on startup by recording transactions from the logs to the respective database files automatically.

Reserved Logs

The directory and information store services independently maintain two reserve files: Res1.log and Res2.log. These files are stored in the Mdbdata and Dsadata directories. If the directory and/or information store service is renaming the Edb.log file and attempting to create a new Edb.log file, and there is not enough disk space to create a new Edb.log file, the reserve log files are used. This is a fail-safe mechanism that is only used in the event of an emergency. When this occurs, an error message is sent to the respective service. The service will flush any transactions in memory that have not yet been written to a transaction log into the Res1.log file, and if necessary, the Res2.log file. When this is completed, the service shuts down and records an event in the Windows NT EventLog. Note that RES (reserve) transaction log files are always 5 MB in size, the same as all transaction log files.

Patch Files

The patch file mechanism was designed for the situation where transactions are written to a database during the backup process. A convenient feature of Microsoft Exchange Server is the ability to back up databases without interrupting service to end users. During the backup operation, data is read from the .edb files.

If a transaction is made to a section of the .edb file that has already been backed up, it is recorded in a .pat (patch) file. If a transaction is made to a section of the .edb file that has not yet been backed up, it is processed and does not need to be written to the patch file. A separate .pat file is used for each database: Priv.pat, Pub.pat, and Dir.pat. Note that these .pat files will only be exposed during the backup process. During an online backup operation, the following occurs:

A .pat file is created for the current database.

The backup operation for the current .edb file begins.

Transactions that must be written to sections of the .edb file that have already been backed up are recorded to the .edb file and the .pat file.

The .pat file is written to the backup tape.

The .pat file is deleted from the Mdbdata or Dsadata directory.

Temp.edb File

The Temp.edb file is used to store transactions that are in progress. Temp.Edb is also used for some transient storage during online compaction.


Purging Log Files

When circular logging is disabled, log files accumulate on the transaction log disk drive until an online normal (full) or incremental backup is performed. During an online backup operation, the following occurs:

The backup process copies the specified database files.

Patch files are created as required (patch files maintain transactions written during a backup operation to the portion of an .edb file that has already been backed up).

Log files created during the backup process are copied to tape.

Patch files are written to tape.

Log files older than the checkpoint at the start of the backup operation are purged. These files are not required because the transactions have already been committed to the .edb files and the .edb files have been written to tape.


Database Circular Logging

Database circular logging uses transaction log technology but does not maintain previous transaction log files. Instead, a few log files are maintained and eventually purged as new log files are created. When transactions in transaction log files have been committed to the database, the existing log files are removed and previous transactions are discarded by this process. Circular logging is enabled by default. Although circular logging helps manage disk space and prevents the buildup of transaction log files, differential and incremental backups cannot be performed because these backups rely on past transaction log files.

When database circular logging is enabled, you may see multiple Edbxxxxx.log files in the Mdbdata or Dsadata directories. This is normal, because Microsoft Exchange Server uses several log files before setting the circular window (wrapping around). For example, the Edb00010.log, Edb00011.log, Edb00012.log, and Edb00013.log files would become Edb00011.log, Edb00012.l log, Edb00013.log, and Edb00014.log.

Microsoft Exchange Server attempts to maintain a window of four log files for circular logging. However, if the server I/O load is large, more than four log files will be used. Log files in excess of four will not be purged until the respective service (information store and/or directory service) is stopped and then restarted.

Verifying That Circular Logging Is Enabled

To verify whether database circular logging settings are enabled, perform the following steps:

In the Microsoft Exchange Server Administrator program, choose a server, and then select Configuration.

From the File menu, choose Properties.

Select the Advanced tab.

View the circular logging settings.

Circular logging can be set separately for the information store and directory, and you can change these settings at any time by using the Administrator program. However, Microsoft Exchange Server will stop the corresponding service and restart it after making changes.


Transaction Logs Recovery

The following example describes how transaction logs are recovered.

The circumstances are as follows:

  • Circular logging is not enabled
  • The transaction logs are stored on a disk separate from the database files.
  • The last full (normal) backup took place two days ago.
  • Due to a hardware failure, such as a bad hard disk, the information store databases become damaged, but the transaction log drive remains intact.

Do the above circumstances dictate that the best you can do is lose two days of production data? The answer is no. Because the transaction logs are complete, they contain all transactions from the point of the last full backup.

In this case, after the hardware is restored, you need to perform a full restore. Do not select Erase All Existing Data, which prompts the backup program to remove all existing log files. The full restore writes the database files and the log files that were backed up with the last full backup.

The restored log files are any log file saved up to the first log file on the current transaction log drive. For example, suppose that the full backup copied Edb00012.log through Edb00014.log. The log files on the transaction log drive would be Edb00015.log and up. The full restore will copy Edb00012.log through Edb00014.log and the information store database files that are part of the backup set.

When the information store service is started, it restores transactions from Edb00012.log through the last log file (such as Edb00019.log) and Edb.log, the most recent log file. After this is completed, the database will be up-to-date. The log files contain signatures, which ensure that these files are included in the sequence to be restored.


Transaction Characteristics

Atomicity

Results of the transaction's execution are either all committed or all rolled back.

In Microsoft Exchange Server, atomic operations are achieved through the use of transaction logs. As mentioned earlier, transactions in the log that haven't yet been committed to the main database file are either rolled forward and committed, or are rolled back if incomplete. This process happens quickly and automatically when the system is restarted.

Consistency

A shared resource (such as a database) is always transformed from one valid state to another valid state. All operations on the Microsoft Exchange Server information store are atomic, and ensure that the data is always in a consistent state. Updating a transaction log to indicate that a transaction has been completely committed back to the main database file is an atomic operation.

Isolation

Transactions are recorded in a serial fashion in a system handling multiple simultaneous transactions. The result of any transaction is the same as if it were the only transaction running on the system. This implies that safe, concurrent access to the data by multiple simultaneous users occurs. Simultaneous user operations cannot interfere with each other in a way that renders the database invalid. The isolation property is enforced by the database underlying the Microsoft Exchange Server information store.

Durability

The results of a transaction are permanent and survive future system and media failures. Microsoft Exchange Server transaction logs implement the principle of durability. If, for example, a portion of a log file is corrupt or unreadable due to physical drive damage, those transactions are rolled back.

Even with media damage, the physical format of transaction logs is carefully designed to reduce the impact of any media failure, through a combination of sequential writes, the creation of new log files every 5 MB, and low-level techniques logging. This last technique maximizes the durability of transactions, even within a partially corrupted log file.

Concern has been expressed that using transaction logs can incur significant overhead because the data must be written more than once (first to the log, then to the main database file). However, the correct use of transaction logs actually improves overall system throughput, for a number of reasons.

When transaction log files are stored on a separate disk, they are written sequentially, rather than through random access. Because the disk drive head doesn't have to seek randomly, the process is faster than random-access writes to the main database file (even with today's fast hard drive subsystems). The transaction log files are then "lazily" committed back to the main database file. (Lazy commit is similar to lazy write, which is the ability to record changes in the file structure cache, which is quicker than recording them on disk, and then later, when demand on the computer's central processing unit (CPU) is low, the Cache Manager writes the changes to the disk.) This can be accomplished efficiently for the following reasons:

  • The transactions are processed asynchronously, when the server has idle cycles.
  • The Windows NT file system (NTFS) and file allocation table (FAT) disk cache systems in Windows NT Server automatically order the writes in the most efficient manner, through classic techniques, to minimize physical head seeks.

In addition, Microsoft Exchange Server recovery techniques work as well for large records as they do for small ones. This is because the transaction logs are smart enough to write only the data that has actually changed. Therefore, if a user changes only a few bytes of a 2-MB document stored in a Microsoft Exchange Server computer, only the actual data pages that are changed are written to the log.


Automatic Recovery Using Transaction Rollback

When the Microsoft Exchange Server information store or directory services is started after abnormal server shutdown, the transaction log file is scanned for incomplete transactions. If incomplete transactions exist, they are rolled back automatically to the state in which they existed before the transaction took place. This automatic recovery operation occurs relatively quickly, because only the most recent transactions in the log must be checked.


Single-instance Storage with Automatic Referential Integrity

Single-instance storage is a key requirement from customers who want to store users' mail centrally, on the server. With single-instance storage, if 100 users on the same server all receive the same message, only a single copy of the message is stored on the server, and 100 pointers to the message are placed in the users' mailboxes. Significant space savings and server performance gains can be realized with single-instance storage.

Microsoft Exchange Server has built single-instance storage capabilities into its information store design from the ground up, as opposed to stringing together existing databases. Single-instance storage is always in effect; it requires no special configuration or administration, and most important, it is intrinsic to the information store. When a message or user mailbox is deleted, the correct thing always happens; messages cannot be orphaned or lost. Pointers cannot get out of sync between files because everything is stored in a single file, and referential integrity is handled internally by the database engine.


Single-Instance Storage with Per-User Storage Limits

With Microsoft Exchange Server, you are given control of storage. Research shows that one of the most common reasons for mail system outages is the inability to limit user storage, which eventually causes servers to fill up and cease working. Therefore, within its shared mail information store, Microsoft Exchange Server enables administrators to set and enforce disk quotas, either as an overall default, or as individual user limits.

Users can be given a warning limit as well as a fixed limit. The fixed limit is enforced by prohibiting the offending user from sending any new e-mail until the user cleans up his or her mailbox. In this way, this user will not miss any critical incoming e-mail messages, and other users won't receive non-delivery notices from the offending user's mailbox.


Online Backups to Tape

Microsoft Exchange Server includes built-in support for running online backups directly to tape media. The server does not have to be shut down, nor do users have to be logged off. Furthermore, Microsoft Exchange Server backup is integrated with Windows NT Server backup, which enables you to back up both Microsoft Exchange Server computers and file servers from the same location. You can perform full, incremental, or differential backups directly to a wide variety of tape devices, from ¼ inch cartridges to high-capacity digital audio tape (DAT) systems.


Examples of Data Recovery

Procedures for the following data recovery scenarios are discussed in this section:

  • Single mailbox recovery
  • Full server recovery
  • .Pst, .ost, and .pab file recovery


Single Mailbox Recovery

Data recovery for a single mailbox may be necessary in the event of an accidental mailbox or mailbox data deletion. In a centrally supported organization, affiliate offices can mail tapes to an internal recovery center.

Instructions for data recovery for a single mailbox are described in this section. These procedures will enable single mailbox recovery for any server in your organization, regardless of the server name.

Before trying any of the example procedures, note the following.

Caution This procedure should not be performed on a server that is in production. As noted below, this procedure requires restoring data to a server that is not part of your production Microsoft Exchange Server site. The dedicated recovery server is installed using the same site and organization name as the production site; however, it is installed by selecting Create New Site.

The following components are required to create this example:

  • A dedicated server with enough capacity to restore the entire private information store database.
  • A backup of the private information store database.
  • Microsoft Exchange Client and Microsoft Exchange Server installation code.
  • Windows NT and the latest Windows NT Service Pack installation code.

Note You must restore the entire information store and then retrieve data from the desired mailbox. You can prepare a server running Windows NT Server and then install Microsoft Exchange Server with the same site and organization name in which the mailbox to be restored resided. Then, restore the information store from a backup tape, log on with Microsoft Exchange Administrator privileges, and assign the Windows NT Administrator ID access to the desired mailbox. Restore mailbox data to a .pst file and then attach the .pst to the desired user profile.

Preparing the Non-Production Recovery Computer

For the fastest recovery, the non-production computer should be running and available for recovery at all times. This computer can be installed as a Windows NT primary domain controller (PDC), backup domain controller (BDC), or member server. The server should also have the appropriate Windows NT Service Pack installed.

Before recovering the data, make sure there is enough disk space for restoring the entire information store from your backup tape. The backup recovery computer should also be equipped with a tape drive that is compatible with the tape drives deployed on production servers. The tape drive should be tested and known to be working at all times.

During the installation of Microsoft Exchange Server, do not join the site. The recovery computer should be a stand-alone computer and should not be joined with your existing production site.

The Process

Log on to Windows NT as an administrator and install Microsoft Exchange Server (using the Complete installation option). Use the same site and organization name that was used on the server from which you are restoring the mailbox. Do not join the site. Note that the server name of the restore computer does not matter for the single mailbox restore procedure. This is because you are only restoring the information store, not the directory.

If you have a dedicated recovery server at each location, you can install Microsoft Exchange Server before starting the recovery. If the recovery server will be shared among sites, it is best to keep a copy of the Microsoft Exchange installation code on the hard drive for quick installation, so you can install Microsoft Exchange Server based on the required site and organization. The paths for this Microsoft Exchange Server installation do not need to match the paths of the production Microsoft Exchange Server installation being recovered.

After you complete the preceding steps, you can install the Microsoft Exchange Client on the recovery server.

Restoring the Information Store from Tape

This procedure assumes that a tape from an online backup is used for the restore. If an offline tape is used, do not choose to start the services after the restore. The following steps describe how to restore the information store from tape.

To restore the information store from tape

Insert the backup tape and log on to the recovery domain as an administrator.

From the Administrative Tools program group, run BACKUP.

From the Operations menu, choose Microsoft Exchange.

Select the tapes icon, and then double-click the tape name.

In the right pane of the Tapes window, choose Org, Site, Server, Information Store.

Choose Restore from the upper part of the Backup menu's main screen.

In the Restore Information window, type the name of the destination server in the Destination Server box.

Select Erase All Existing Data, Private, Public, Verify After Restore, Start Service After Restore, and then choose OK. After you choose OK, the following message appears:

"You are about to restore Microsoft Exchange components. The Microsoft Exchange services on the destination server will be stopped."

Choose OK.

In the Verify Status window, choose OK.

After the restore is completed, start the Directory Service service.

At the command prompt, switch to the Exchsrvr\Bin directory, and type

isinteg –patch

This will run the ISINTEG troubleshooting utility in patch mode. After you run ISINTEG, a message appears stating that the databases have been successfully updated. Now you can start the Microsoft Exchange Server information store and the other services.

In Control Panel, double-click the Services icon, and then verify that the relevant Microsoft Exchange Server services are running.

Recovering a User's Mailbox

Follow the steps described below to recover a user's mailbox.

To recover a user's mailbox

Log on to the recovery server using the Windows NT Administrator ID.

In the Administrator window, choose Servers, and then select a server.

From the File menu, choose Properties.

Select the Advanced tab.

Under DS/IS consistency adjustment, select All Inconsistencies.

Choose Adjust.

Select Recipients, and then double-click a user's mailbox name.

Select the General tab, and then select Primary Windows NT Account.

Choose Select An Existing Windows NT Account, and then choose OK.

In the Add User box, select Administrator, and then choose Add.

In the User Property window, choose OK.

In the Microsoft Exchange Client, start the Microsoft Exchange services.

Configure a profile for the appropriate user.

Add a .pst file to the profile.

Restart the Microsoft Exchange Client.

In the left pane, select Mailbox - Username.

Select the first folder or item in the list on the right pane.

From the Edit menu, choose Select All.

From the File menu, choose Copy.

In the Copy dialog box, select the appropriate .pst file, and then choose OK. All data will be copied to this .pst file.

Copy the .pst file to the destination location.

Add this .pst file to the user's profile on the production server or send the .pst file to the user with instructions.

If you have network access, you can copy the recovered .pst file to the appropriate server.

The following figure illustrates the Microsoft Exchange Server single mailbox recovery process.

The single mailbox recovery server can be maintained online with production servers because the server name does not need to be the same as the production server running Microsoft Exchange Server. This recovery server, however, should not perform directory service replication with the production servers.

The following figure illustrates a topology for maintaining a spare server for single mailbox recovery. Note that the spare server "Sabc" is not joined to the production site. However, the server was installed using the same site name and organization name as the production site.


Full Server Recovery

You can restore data from one full Microsoft Exchange Server to a different computer, and you can also move Microsoft Exchange Server data from one computer to a new computer. This section describes how to restore data from one Microsoft Exchange Server computer to a different computer.

A full server recover is a special case because Windows NT is reinstalled and a new registry is created. In this situation, a new Windows NT security identifier (SID) must be created for the recovery computer in the domain, as outlined below.

Note The information in this section is also useful for moving a Microsoft Exchange Server installation to a more powerful server for a hardware upgrade. Keep in mind that the Windows NT registry can be restored to the same physical computer. This may be useful when a hard drive is being replaced on the same computer. In this case, if you restore the Windows NT registry, the computer maintains its unique SID, so you do not need to create a new SID by using the procedures below.

In addition to performing a full restore of the Microsoft Exchange Server databases (information store/directory service), it may also be necessary to restore the Windows NT Security Accounts Manager (SAM) database. Microsoft Exchange Server automatically adds two accounts upon initial installation: the Windows NT service account and the Windows NT account that were logged on to during the initial installation of the software. Although both accounts receive special privileges during installation, to restore the Microsoft Exchange Server directory service, you only need the Windows NT account SID that was originally used during the installation. The Microsoft Exchange directory service will not be accessible unless this SID exists in the Windows NT environment. If no domain controllers of the original domain are available, you must restore the Windows NT primary domain controller SAM.

Following are the requirements for a full server recovery.

  • A full backup of the information store and directory.
  • A replacement computer with the same hardware capacity as the production server.
  • Access to the original Windows NT SAM.
  • Production server configuration sheet.
  • Microsoft Exchange Server installation code.
  • Windows NT Server and the latest Windows NT Service Pack installation code.
  • Microsoft Exchange Production Server configuration sheet.

A full server recovery is more complex than a single mailbox recovery. A full server recovery is defined as the ability to restore an original production Microsoft Exchange Server such that all Windows NT security and configuration information is recovered, as well as Microsoft Exchange Server configuration information and other data. A full server recovery enables users to use their current passwords to log on to their mailboxes when a recovery server is deployed.

Where a single mailbox recovery requires that only the information store be restored, a full server recovery requires that both the information store and directory service be restored. Microsoft Exchange Server relies on Windows NT security for providing access to mailbox data. Microsoft Exchange Server uses Windows NT account SID information in object properties within the Microsoft Exchange Server directory.

For a successful directory service recovery, two key conditions must be met:

  • The directory service must be restored to a Windows NT Server computer that has the same site, organization, and server name as the production server.
  • The recovery server must have access from the domain in which Microsoft Exchange Server was originally installed.

A full-server disaster recovery involves three computers. Two computers will be in production; one is a non-production or non-essential computer (meaning that such a computer can be in production performing some other task, but will be available at any time for recovery). One computer is a PDC. A second computer, usually a Microsoft Exchange Server computer, is configured as a BDC. The third computer is designated as a recovery server.

The requirement for a configuration that incorporates a PDC, BDC, and recovery server is due to the way in which Microsoft Exchange Server uses the Windows NT SAM database to provide authentication to directory objects. A full-server restore including the information store and directory requires access to the SAM from the domain in which the Microsoft Exchange Server computer was first installed.

For example, if you have one Microsoft Exchange Server computer in a site, and this server also acts as a PDC, you can have a recovery server offline. The Microsoft Exchange information store and directory are backed up nightly. If this server fails, a backup PDC with Microsoft Exchange Server can be built from scratch and the information store can be restored. When the Microsoft Exchange Server directory is restored, it expects the security properties of all directory objects to match the Windows NT SAM for the respective accounts.

Caution Because the backup computer was rebuilt as a PDC, a new Windows NT SAM is created. The restored Microsoft Exchange directory objects will not match the SAM objects, you will not be able to log on to the Microsoft Exchange Server Administrator program, and the Microsoft Exchange Server services will not be able to start. All restored data will be inaccessible if the Microsoft Exchange directory is restored in this case. Although you can restore the information store without the directory to access the data for each mailbox, this will only provide administrator access to mailbox data, and it is not considered full server recovery. The original Microsoft Exchange Server directory information will be lost from the production server.

As an example, suppose that there is a dedicated PDC, a production Microsoft Exchange Server computer that acts as a BDC, and a recovery server. The production Microsoft Exchange Server computer fails. You can build a Windows NT domain controller from the recovery server with the same computer name as the Microsoft Exchange Server computer that failed.

You can connect this to the domain as a BDC, which provides you with a copy of the SAM from the domain in which the production Microsoft Exchange Server computer resided. Using Server Manager, you first delete the original computer name, the BDC definition, from the PDC. Add it again during the BDC installation.

This procedure is necessary because each computer name receives a unique SID when it is added to the domain, and you will need a new SID for the recovery computer. After you have done this, install Microsoft Exchange Server using the same site and organization name. By default, the same server name will be used because Microsoft Exchange Server uses the computer name to create the Microsoft Exchange Server name. If you are recovering a server and joining an existing site during this reinstallation, see the Microsoft Exchange Server Administrator's Guide.

Creating a New SID for the Recovery Server

Install Microsoft Exchange Server on the new or repaired server, but do not replicate it with the existing organization.

Give the server its original organization and site name.

Run Setup. Do not join an existing site.

Create a new site with the same organization and site name.

After Setup is complete, upgrade the recovery server to the same Microsoft Exchange Service Pack as the production server.

Now you can restore the information store and directory from the last Microsoft Exchange Server production computer. Note that you could have added the recovery server to the production domain as a member server instead of a BDC.

Using a Backup Tape of the Information Store and Directory Service for a Server Recovery

The following is an example of a server recovery using a backup tape of the production server information store and directory service. Note that a normal (full) online backup of the information store and directory was performed. During the Microsoft Exchange Server software installation, do not join the site. Instead, select Create New Site. This is because you have a backup copy of the Microsoft Exchange Server directory database. Even though you chosen to create a new site, when you restart the server, it will synchronize automatically with other servers in the site because the knowledge of being in a site is stored in the directory database.

Preparing the Recovery Computer

When you prepare the recovery computer, note that you need to install Windows NT with the same computer name as the Microsoft Exchange Server computer that failed. If the production Microsoft Exchange-based server is a BDC, add the recovery server to the production domain as a BDC. As mentioned earlier, you need to first delete and then re-add the computer name on the PDC to create a new SID for the recovery computer. The recovery server should have a version of the Windows NT Service Pack installed that matches the configuration of the production server. Also, make sure that there is enough disk space for restoring the entire information store and directory from your backup tape. This computer should also be equipped with a tape drive that is compatible with the tape drives deployed on production servers. To expedite the restore process, maintain a copy of the Windows NT installation code and Service Pack on the hard drive of the recovery computer. For information on settings for protocol addresses, partitioning information, protocols, options, tuning, and other options, see your production Windows NT Server configuration data.

Creating a New Site But Not Joining the Existing Site

The following process will enable you to create a new site without joining the existing site.

Log on to Windows NT as an administrator and install Microsoft Exchange Server using the same site and organization name that was used on the server from which you are restoring the mailbox.

Use the Setup command to install Microsoft Exchange Server. Do not type Setup /R. This creates a problem that you will encounter when attempting to upgrade this recovery server to the latest Microsoft Exchange Service Pack.

When prompted, select Create New Site. Note that the server name of the recovery server matches that of the production computer.

Select the same service account that you used for the production server.

Run the Microsoft Exchange Performance Optimizer to optimize Microsoft Exchange Server for the same configuration that was used on the production server. For more information, see your production server configuration documentation.

After Microsoft Exchange is installed, upgrade this recovery server to the same Microsoft Exchange Service Pack as the production server.

Install Microsoft Exchange Client on the recovery server.

Performing the Restore

This procedure assumes that you are using an online backup tape for the restore (the backup was performed while Microsoft Exchange Server services were running). If an offline tape is used, do not choose to start the services after the restore.

After the restore, at the command prompt, type isinteg -patch to run the ISINTEG tool. Make sure that the directory service is started first, and then start the information store service.

To perform the restore

Insert the restore tape.

In the Administrative Tools group, double-click the Backup icon.

Double-click the Tapes icon.

Double-click Full Backup Tape.

In the right pane, select the directory and information store that you want to restore.

Choose Restore.

In the Restore Information dialog box, select the following check boxes: Erase all existing data, Verify After Restore, and Start Service After Restore.

Note If the public information store is on a separate computer, do not select the Erase all existing data check box. Instead, select the following check boxes: Private, Public, Verify After Restore, and Start Services After Restore. If you erase the public store inadvertently, contact Microsoft Technical Support.

Type the name of the destination server in the Destination Server box.

Choose OK.

If the directory service and information store were backed up using separate backup jobs, do not start these services until both have been restored.

When the restore prompt appears, choose OK. This opens the Restore Status dialog box.

After the restore is completed, choose OK.

Close the Backup program.

Reviewing Mailboxes for Windows NT Account Association

To verify that your users' mailboxes have a Windows NT account associated with them, follow these steps.

In the Microsoft Exchange Administrator program, select a server, and then choose Recipients.

Double-click a user's name.

Review the Primary Windows NT Account box to verify that the Windows NT account matches the mailbox.

Repeat this procedure as needed for each user.

Testing a User's Logon from a Client Workstation

To test a user's logon from a Microsoft Exchange Client workstation, follow these two steps.

Start the Microsoft Exchange Client.

Verify that the user's password is accepted.

Authoritative Restore

If directory information on the restored server changes or automatically gets purged, you may be experiencing an undesired backfill state.

When previous replicated changes from the restored server are replicating back from another server, the other server may have a change record that is more up-to-date than what is reflected in the restored database. In this case, backfilling has occurred.

The Authoritative Restore tool (Authrest.exe) available on the Microsoft Exchange Server compact disc enables you to force a restored directory database to replicate to other servers after restoring from a backup. For assistance on using this tool, contact Microsoft Technical Support.

Normally, a restored database is assumed to be more out-of-date than the collective information held on all other directory replicas in the organization. A restored directory normally replaces its information with more recent data held by other servers. This functionality is appropriate when the reason for the restore is that a database or server was destroyed, but it is not appropriate in all cases. For example, if an administrative error deleted thousands of mailboxes or vital configuration information, the goal of restoring from backup is not to restore one server to functionality, but to move the entire system back to where it was before the undesired changes were made.

Without the Authoritative Restore tool, you would need to restore every server in the organization from a backup that predates the error, or else you would have to restore every server in the site, and then force all bridgeheads in other sites to resynchronize from scratch. If only one server was restored, or if servers were restored one at a time, the restored server would quickly overwrite its restored data with the more recent (incorrect) information held by all other servers in the site.

The Authoritative Restore tool enables you to restore one server (presumably the server with the most recent pre-mistake backup) rather than all servers. Normal replication then causes the restored information to spread to all servers throughout the organization.

The Authrest.exe file is available from the Support\Utils\<platform> directory on the Microsoft Exchange Server compact disc.


.Pst, .Ost, and .Pab Recovery

Data recovery includes backing up and restoring three types of files:

  • .Psts
  • .Osts
  • .Pabs

Before restoring any of these files, however, read the next section, which describes how to restore databases by using the correct version of Microsoft Exchange Server with the accompanying Service Pack.

Restoring Service Packs

When restoring databases, it is important that you run the restored databases under the same Microsoft Exchange Server version that they previously ran under. Therefore, do not start services until all code is up-to-date. For example, if you are using Microsoft Exchange Server Service Pack 2 (SP2), but have the original server compact disc and SP2 code, you should have the SP2 code loaded before running Microsoft Exchange Server with your restored databases from an SP2-level server.

After you have installed the correct Service Pack, you can restore your database files by replacing the new databases that were installed by running the Setup program. When you do so, make sure that you follow the appropriate restore procedures.

Note If you run Setup /R, it will not create the .Dir.edb, Pub.edb, and Priv.edb files. (Normally these files are created with the organization and site name given during setup.) Setup /R, however, copies the Dir.edb from the Microsoft Exchange Server compact disc exactly the way it is. You will not be able to start the directory service with the default Dir.edb.

You also must restore all database files (Dir.edb, Pub.edb, and Priv.edb). If you plan to restore only the information store and not the directory, then do not run SETUP /R.

Restoring from an .Ost File After Mailbox Deletion

.Ost files are "slave" replicas of Microsoft Exchange Server folders. If you delete the master, the slave is orphaned. If the original Microsoft Exchange profile was not modified, then you can start the process offline with the old .ost file, and recover the data by copying it to a .pst file. However, if the old profile was deleted or modified (for example, if you used the profile to log on to the new mailbox), the data is lost.

The reason data is lost is due to the way in which security is enforced on .ost files. You cannot perform Windows NT authentication while you're offline. Instead, you have to prove that you can log on to the server-based master before the .ost file will give you local access.

Microsoft Exchange Server does this by creating an encrypted "cookie" from your mailbox's unique entry ID, while you have successfully logged on to the server. This cookie is securely stored in your Microsoft Exchange Server profile. Your profile stores the key for the .ost file. Every time you try to access the .ost file, it checks your profile for the existence of this key.

The exception to making the .ost file non-recoverable occurs if one of the following takes place:

  • You delete the master server mailbox.
  • You also delete or modify the profile containing the key to the .ost file.

Using the Inbox Repair Tool to Repair .Pst and .Ost Files

The Inbox Repair Tool repairs.pst and .ost files. This tool is similar to the MMF check capability in Microsoft Mail and is installed in the Microsoft Exchange Client subdirectory.

The Inbox Repair Tool performs eight checks on the selected file. Note that during repair, you can choose to back up the existing file before making the repair. The following figure shows the Inbox Repair Tool after a scan has been performed.

Security IDs, Secret Objects, and Windows NT-Based Computer Accounts

The following figures show a Windows NT Secure Channel in a normal production environment.

Each Windows NT Server computer has a unique SID that is used for domain authentication. Note that the Windows NT SID for EXS1 is xyz. This SID is used solely for purposes of this example, and is not the actual SID format. To connect to the domain, the Windows NT BDC (member server) must have a matching SID and local security authority (LSA) password that enables authentication to take place. The following figure illustrates a secure channel failure.

This figure demonstrates what happens if you do not first delete and then re-add the Microsoft Exchange Server computer account before installing a recovery server. If a recovery server is rebuilt by installing Windows NT from scratch, and the same computer name is used, NETLOGON will fail because the old computer account and SID remain in the domain SAM and can only be reset from within the Server Manager program by deleting and re-adding the computer account.

The following figure shows a re-established computer account.

When the old computer account is deleted and then readded to the domain SAM, the SAM entry is first set to an initialize state. When the new server is added, a local LSA secret object is created along with a SID, thus synchronizing the LSA secret object (stored locally on the BDC or member server) with the SAM object for the respective computer. In addition, a password is generated that is used whenever the BDC or member server computer logs on to the domain. This process creates a secure channel between the BDC and the PDC. The secure channel password is changed automatically by NETLOGON to prevent the password from being discovered.

Note that the LSA secret object is created by Setup during the initial installation or when a server joins a domain. The SAM computer account is created by the Server Manager program.


Tips and Techniques for Dependable Disaster Recovery

There are a number of things you can do on a routine basis to ensure that your disaster recovery plan is successful. Review the topics in this section when you understand what you need to do to backup and recover files.


Create and Verify Daily Backups

This is a critical step in disaster recovery. It sounds simple, but you can only recover data if you have a valid backup. Failure to verify backups is one of the most common mistakes made. It is often assumed that backup tapes are being swapped and that data is being properly backed up. It should be a daily routine to review all backup logs and follow up on any errors or inconsistencies. Furthermore, full (normal) backups reset and remove transaction logs. This results in free disk space. Note that this is less of an issue if circular logging is enabled. If circular logging is not enabled and daily full backups are failing, transaction logs will not be purged and you can fill up the entire transaction log disk drive.


Perform Periodic File-Based Backup

To capture all configuration data, it is best to perform a full file-based backup periodically. Services should be shut down so that open files can be backed up. This will ensure that you have backed up all possible Microsoft Exchange related files. You may want to perform this backup during scheduled maintenance. Note that file-based backup is not required for backing up the information store and directory databases. Online backups are recommended for backing up the information store and directory.


Standardize Tape Backup Formats

Recovery equipment must be compatible with production tape equipment. If you deploy a new type of tape drive, make sure you that you use a compatible model for your recovery equipment. You should also test reading and restoring production tape backups on the tape drive used for recovery.


Deploy a UPS and Test it Periodically

Do not take the approach that if the Microsoft Exchange-based server does not fail during a power outage, that all other servers have not failed. Make sure you are protected by an uninterruptible power supply (UPS). Many computer rooms are supposedly UPS protected. Even though this may be the case, it is possible that not all outlets are UPS protected. If you do not have a dedicated UPS, make sure that you speak with the local electricians or operations personnel and perform a test. Also note that server class UPS system batteries can wear out every three years and require replacement.


Review the Environment When Placing Production Servers

Inspect the area when deploying servers. Make sure that the environment is receptive. For example, you should ensure that there is enough power, and if possible, dedicate power lines for your equipment. Review existing amperage and new amperage requirements. Make sure that servers are not placed under fire sprinklers. Also, make sure that your servers are in a physically secure location and that the room temperature is acceptable.


Perform a Periodic Fire Drill

A periodic fire drill is an effective way to measure your ability to recover from a disaster and to certify your disaster recovery plans. Conduct this in a test environment and attempt a complete recovery. Make sure to use data from production backups. During this process, record the time it takes to recover. This information will assist you in estimating the time it will take to recover in a real disaster recovery situation. From personal experience, up to one-third of recovery time can be spent in preparing and getting the correct tools in place to complete the job. For maximum effect, provide no notice to your staff that you are performing a drill. This will be the most valuable experience you will have in your disaster recovery planning.


Check Windows NT EventLogs Daily

Take a proactive approach and review logs regularly. This can help you identify problems before they have an impact. A number of logging tools are available in Microsoft Exchange Server and this should be leveraged.


Create a Disaster Recovery Kit

Planning ahead reduces recovery time. It is critical to build a kit that includes items such as an operating system configuration sheet, hard drive partition configuration sheet, hardware configuration sheet, Extended Industry Standard Architecture/Micro Channel Architecture (EISA/MCA) configuration disks, Microsoft Exchange Server configuration sheet, Windows NT emergency repair disk, Microsoft Exchange Performance Optimizer settings sheet, and so on.


Publish a Microsoft Exchange Server Maintenance Schedule

Perform basic preventive maintenance on a regular basis. The robustness of Microsoft Exchange Server can be compromised by failure to perform basic preventive maintenance routines when deploying servers. A Microsoft Exchange Server computer is no different than a car that requires oil changes and other maintenance. Unlike mainframes, servers are often overlooked when it comes to scheduling downtime for maintenance. It is a simple formula: Planned maintenance generally reduces unplanned downtime. It is important to set user expectation levels by publishing a maintenance schedule especially when users expect service 24 hours per day, 7 days per week. Maintenance is inevitable because the nature of the data processing business includes service pack updates, software upgrades, and hardware upgrades. Although rare, it might be necessary to take down the information store service to reduce the size of store files by using the EDBUTIL troubleshooting utility. This utility is available on the Microsoft Exchange Server compact disc.


Determine Downtime Cost

Determining the cost of downtime is useful when justifying the purchase of recovery equipment. There are different models for calculating the per-hour downtime cost, which varies for each business. These calculations include lost orders per hour, delayed financial transactions, and the cost of delayed time-sensitive market decisions. For more information on justifying disaster recovery expenditures, see the National Computer Security Association News (July 1996).


Consider Maintaining Off-Site Tapes and Equipment

Due to legal or security issues, certain companies choose not to send backup tapes to a third party off-site location. An alternative is to send tapes to an off-site location within the same company.


Dedicate Recovery Equipment and Build a Recovery Lab

It is important to dedicate hardware. Don't allow test equipment to become production equipment without replacement. Make sure the recovery equipment is always in working order and available at a moment's notice. Some companies purchase recovery equipment, but then install "test only" software. They become dependent on this equipment for production use. In short, keep recovery equipment in a dedicated mode. Another reason to build a lab is for recovery purposes. When you use the EDBUTIL troubleshooting utility, up to two times the disk space of the largest production server information store database is required for recovery and database defragmenting. It is more cost effective for an organization to maintain one recovery server with sufficient disk space.


Keep Accurate Records of All Configurations

This is necessary when configuring the recovery server. Records include Windows NT tuning settings, path information, protocol addresses, Microsoft Exchange Server connector configurations, and so on. These records should be part of the disaster recovery kit discussed earlier.


Take a Proactive Approach to Monitoring the Information Store

Monitor the growth of the information store and server performance. Be prepared with a plan to remedy any issues. Windows NT disk space alerts can be set up to monitor remaining disk space. Performance Monitor objects exist for the information store and should be used.


Devise an Archiving Plan

An archiving plan enables your users to move server-based messages into local store files. This reduces the size of the server-based information store. Have users store their .pst files on local drives or on a separate disk or server from the information store. Dedicate a file server for .pst archiving if required. Otherwise, data will be reduced in the information store but added to another area of the same disk or logical drive. The impact will be greater because .pst storage maintains messages in both Rich Text Format (RTF) and ASCII format. Note also that disk space limits cannot be set on .pst files. Make sure to include all sensitive data in backup strategies, including users' .pst files. Use encryption when creating .ost files and .pst files.


Consider Microsoft Exchange Server Roles

You should always avoid making your Microsoft Exchange Server computer a PDC. If this computer becomes unavailable, an alternate domain controller must be promoted to become the primary domain controller. If the Microsoft Exchange Server computer is not the PDC, you do not need to worry about promotions and demotions of domain controllers in a recovery situation.

Some companies prefer to place the Microsoft Exchange Server on a BDC in the accounts domain so that a second computer is not required for Windows NT authentication in remote offices. This can save the cost of purchasing another computer. However, make sure to account for additional RAM overhead for the Windows NT SAM, in addition to Microsoft Exchange Server memory requirements. Windows NT domain controllers require RAM equal to 2.5 times the size of the SAM.

If the Microsoft Exchange Server computer is a member server and not a PDC or BDC, additional memory overhead for the domain SAM is not required. However, for remote offices, companies can save money by using the local Microsoft Exchange Server to provide authentication (BDC) and messaging services.

Note For a proper directory service restore, access to the original SAM is required. Never install a Microsoft Exchange Server computer in a domain that does not have a BDC.

An alternative is to place the Microsoft Exchange Server computers in a large resource domain that trusts each account's domain. In this case, the Microsoft Exchange servers can be placed on BDCs without incurring significant memory overhead because the SAM for the Microsoft Exchange Server resource domain will be relatively small in size.


Locate Transaction Log Files on Separate Dedicated Physical Disks

This is the single most important aspect of Microsoft Exchange Server performance. However, there are recovery implications to maintaining transaction log files on separate dedicated physical disks. Transaction logs provide an additional mechanism for recovery.


Disable SCSI Controller Write Cache

To avoid the potential for data loss, disable the small computer system interface (SCSI) controller write cache. At a programming level, if the write-through flag is set, Windows NT will not use buffers and therefore, when a program receives a write complete signal from Windows NT, it is guaranteed that the write was completed to disk. This is critical to the Microsoft Exchange Server transaction logging process. If write cache is enabled, Windows NT thinks that a write has been made to disk and will inform the calling application of this false information. This could result in data corruption if a crash is experienced before this lazy-write operation makes it to disk.


Disable Circular Logging if Possible

Although circular logging can help conserve disk space, it disables incremental and differential backups. In addition, transaction log history is cyclical and cannot be restored. If a solid backup strategy is in place, transaction log files are purged on a regular basis, which frees disk space.


Place Limits on Information Store Attributes

Configure mailbox storage limits and maximum age of server-based messages. Also limit MTA message sizes and the size of messages that users can send. These precautions will limit the amount of data you must back up and restore in case of a disaster.


Configure MTAs

Configure the MTA frequency so that queues are cleared quickly. This prevents queued messages from accumulating in the information store. Also, design a redundant MTA path so that messages keep flowing in the event of a link outage. It is important that MTAs are able to keep up with the traffic that flows through them. This reduces messages in the information store and enables timely message delivery.


Equip Servers with Sufficient Disk Space

As mentioned earlier, offline maintenance and repair routines require up to two times the disk space of the database file being administered with the EDBUTIL utility. The following figure shows a sample configuration outlining the distribution of Microsoft Exchange Server information and local store data.

For optimal performance and recoverability, the operating system drive should be mirrored, transaction logs should be placed on a dedicated physical drive (this can also be mirrored), and the Windows NT swap file and the information store should be placed on a mirror or RAID 5 disk set.


Backup Strategies

To establish an effective backup strategy, it is important to understand the many options available to you. For example, is it better to perform full backups every night? What are the tradeoffs? Depending on business requirements, backup strategies can vary.


Time Required for Backing Up

The time required for backup depends on the backup type, as shown in the following figure.

As this figure shows, performing a full backup on a daily basis requires the most time. For smaller databases, this is not an issue. However, when stored data is in the gigabyte range, it is not desirable to perform daily full backups. A full backup in combination with an incremental and or differential backup may be more appropriate in your situation.

Example A: full daily backup

This backup is performed on the following schedule: SU:F, M:F, T:F, W:F, TH:F, FR:F, S:F. The following table lists the advantages and disadvantages of this backup routine.

Advantages | Disadvantages
Always removes transaction log files | Impacts server performance the longest
Only requires one tape restore | Requires the most tape space
Simple schedule enables circular logging | Daily tape swaps usually required

Example B: Full plus one incremental backup

This backup is performed on the following schedule: SU:F, M:I, T:F, W:I, TH:F, FR:I, S:F. The following table lists the advantages and disadvantages of this backup routine.

Advantages | Disadvantages
Always removes transaction log files | Requires two tapes to restore
Multiple full backups on separate tapes | Must have knowledge of backup cycle
Incremental has much less performance impact | Circular logging must be disabled.
Tape rotations are less frequent. |
At most, two tapes required for restore |

Example C: full plus two incremental backups

This backup is performed on the following schedule: SU:F, M:I, T:I, W:F, TH:I, FR:I, S:F. The following table lists the advantages and disadvantages of this backup routine.

Advantages | Disadvantages
Always removes transaction log files | Restore requires a full backup tape, plus each incremental (in this case, up to three tapes)
Full backups are relatively frequent. | Must have knowledge of backup cycle
Little performance impact on server | Circular logging must be disabled.
Incremental requires minimal tape space. |

Example D: full plus two differential backups

This backup is performed on the following schedule: SU:F, M:D, T:D, W:F, TH:D, FR:D, S:F. The following table lists the advantages and disadvantages of this backup routine.

Advantages | Disadvantages
Full backups are frequent. | Differential backups do not remove log files.
At most, two tapes required for restore | Circular logging must be disabled.
Little performance impact |
Differential requires minimal tape space |

Summary

The strategy you choose must fit your business requirements. A general rule is to use full daily backups for small data sets. For large data sets use a combination of full, incremental, or differential backups, as outlined in examples B, C, and D. This minimizes the performance impact and the required tape space.

One common question is whether it is possible to maintain a live "hot spare" server running at all times for Microsoft Exchange Server recovery. The answer depends on how you define a hot spare.

To perform a complete server restore (which includes restoring the directory and the information store), you must configure a recovery server with the same computer name. For this reason, a secondary recovery server cannot remain online because duplicate NetBIOS names will exist. Also, two computers with the same name cannot exist within a Windows NT domain. Without restoring the Microsoft Exchange Server directory, you can recover individual mailboxes easily. However, must also reconfigure Windows NT security. This is a manual process, and therefore can be quite complex.


Examples of Online Backup Automation for IS/DS

Use the following procedure to automate online backups of the information store and directory service.

From the Windows NT Resource Kit compact disc, install the Winat.exe program on the local Windows NT directory of your local computer (for example, on the Winnt35 directory).

Create a Windows NT common group called Microsoft Exchange Server Backup.

Create an icon for the Winnt35\Backup.log file. This provides quick access to review the backup log.

Copy the Ntbackup.exe icon from the Administrative Tools group to the Microsoft Exchange Server Backup group.

Create an icon for Winat.exe in the Microsoft Exchange Server Backup group.

In Control Panel, double-click the Services icon.

Select the Schedule service and choose Startup. Configure for automatic startup and assign an ID that is a member of the Windows NT Backup Operators group. Make sure to enter the correct password. If the administrator ID password changes, you must change the password for the Schedule service.

Start the Schedule service.

Create the backup batch file. Name this file Back.bat and save it in the Winnt35 subdirectory.

Run the Winat.exe program and schedule the Back.bat file. You do not need to have a logon session on the computer in which Winat.exe is running because the Schedule service will log on to perform the operation under the defined security context. Set the batch job for interactive mode.

Sample Batch File for Online Backup

Following is a sample batch file you can use for backing up your files while the server remains online.

rem ** 3/7/96 Backup Written by <name>

rem ** This will back up the information store and directory service on <server_name 1> and <server_name 2>.

ntbackup backup DS \\Server_name1 IS \\Server_name1 /v /d "Server-name1 IS-DS" /b /t Normal /l c:\winnt35\backup.log /e

ntbackup backup DS \\Server_name1 IS \\Server_name1 /a /v /d "Server_name1 IS-DS" /b /t Normal /l c:\winnt35\backup.log /e

exit

Sample Batch File for Offline Backup: Example 1

You may need to experiment with the order in which you stop the services, so that you are not prompted when a service is dependent upon the one you are stopping.

rem ** Stop Microsoft Exchange services.

rem ** You can stop Microsoft Exchange services and restart them automatically to backup.

rem ** Files that a particular service may hold open

REM // stop all services

echo Stopping Services...

net stop MSExchangeMSMI

net stop MSExchangePCMTA

net stop MSExchangeFB

net stop MSExchangeDX

net stop MSExchangeIMC

net stop MSExchangeMTA

net stop MSExchangeIS

net stop MSExchangeDS

net stop MSExchangeSA

ntbackup backup c:\ d:\ /a /v /d "Full File Based Backup" /b /l c:\winnt35\backup.log /e

REM edbutil OPTIONS

net start MSExchangeSA

net start MSExchangeDS

net start MSExchangeIS

net start MSExchangeMTA

net start MSExchangeIMC

net start MSExchangeDX

net start MSExchangeFB

net start MSExchangePCMTA

net start MSExchangeMSMI

Sample Batch File for Offline Backup: Example 2

You can start and stop PCMTA services by enclosing the service name in quotation marks. You can determine the service names from the Microsoft Exchange Server Administrator program, the Windows NT Control Panel, or by viewing the Windows NT registry.

If you are viewing the Windows NT registry, select

HKEY_LOCAL_MACHINE, SYSTEM, CurrentControlSet, Services.

All services are listed in alphabetical order.

rem Batch File To Stop and Restart Microsoft Exchange Services

rem For File Based Backup

echo Stopping Services ...

net stop MSExchangeMSMI

net stop MSExchangePCMTA

net stop MSExchangeFB

net stop MSExchangeDX

net stop MSExchangeMTA

net stop MSExchangeIMC

net stop MSExchangeIS

net stop MSExchangeDS

net stop "PC MTA - HUB"

net stop MSExchangeSA

ntbackup BACKUP d:\exchsrvr\mdbdata /v /d "File Based Backup" /b /l c:\winnt35\backup.log /e

net start MSExchangeSA

net start MSExchangeDS

net start MSExchangeIS

net start MSExchangeMTA

net start MSExchangeIMC

net start MSExchangeDX

net start MSExchangeFB

net start MSExchangePCMTA

net start MSExchangeMSMI

net start "PC MTA - HUB"


Windows AT Command Scheduler and the Windows NT Schedule Service

When you use the Windows AT Command Scheduler, the Windows NT Schedule service runs all jobs that have been scheduled. Because batch jobs are run in the context of the Schedule service, Windows NT security must be considered. When configuring the Schedule service, configure the account to be a member of the Windows NT Backup Operators group. This enables a full backup of the information store and directory.

The following figure shows the Windows AT Command Scheduler.

Make sure that the Back.bat jobs are set for interactive. This is required by the Ntbackup.exe program.


Information Store Recovery: a Real-World Example

Although extremely rare, the information store can become corrupted due to hardware failure or device driver failure. This section describes an actual information store recovery. The recovery procedure used was a last-resort operation. In this case, no recent backup was available and circular logging was enabled, thus preventing the playback of past transactions.


Monitoring Backup Logs and the Windows NT EventLog

When online backup of the information store fails, this may indicate that your information store is running in an inconsistent state. For this reason, it is critical to review backup logs and the Windows NT EventLog on a regular basis.

In this case, the following errors appeared in the Windows NT EventLog:

Event ID: 23 ; Source: EDB; Type: Error; Category: Database Page Cache; Description: MSMicrosoft ExchangeIS ((458) Direct read found corrupted page error -1018 ((-1:550144) (0-589866), 486912 1162627398 3480849804). Please restore the database from a previous backup.

Event ID: 8010; Source: NTBACKUP; Type: Error; Category: None; Description: Microsoft Exchange services returned 'c80003fa' from a call to 'BackupRead()' additional data.

The Ntbackup log revealed that the online backup was failing 2.2 GB into a 3.4-GB information store backup. Until the problem could be resolved, an offline backup strategy had to be put into effect. The batch file described earlier in this chapter, in "Sample Batch File for Offline Backup: Example 2" section, was used with the Windows NT AT Command Scheduler to perform the following functions:

  • Shut down Microsoft Exchange Server services.
  • Perform an offline backup.
  • Restart Microsoft Exchange Server.

Note that in this case, the information store appeared acceptable from a user perspective and remained functional during business hours.


Recovery Procedure

This section describes the procedure used to repair the information store.

Note This example is provided for informational purposes; you should implement the procedures described only with the assistance of Microsoft Technical Support. You should also note that the procedure was performed strictly in a test lab prior to being implemented in production. It is strongly recommended that you pursue the same strategy and perform all repair testing in a lab environment prior to implementing this procedure in a production environment.

The information store Prov.edb file was repaired with the EDBUTIL utility. The procedure was run on an IBM 720 server with 8-GB disk capacity and mirrored drives. The Priv.edb file was 3.4 GB.

Warning If you run the EDBUTIL utility, note that the edbutil /d /r command will delete messages. Therefore you should use this command only as a last resort.

The EDBUTIL /D command, however, does not delete messages and is used for offline defragmenting and reducing .edb file size. When running EDBUTIL with the /d (defragment) option, you will need available disk space up to one times the size of the .edb files you are running against (or a disk two times the size of the EDB). For example, if your Priv.edb file is 3.4 GB and there is no empty space in the file, you will need 3.4 GB of available space for the defragment operation. This does not include any swap file growth that can temporarily occur. If there is 4 GB of empty space in the Priv.edb file, you will need 3 GB of available space.

By default, the Tempdfrg.edb file will be used to rebuild the .edb file. When running EDBUTIL, you can use the /t option to redirect the Tempdfrg.edb file to a non-default location or to rename it. You cannot however, redirect this temporary file to a LAN-connected drive.

The following table provides estimated times for the backup actions that were performed, and a description of each action.

Action | Time | Description
Ntbackup.exe | 2.5 hours | All Microsoft Exchange Server services were stopped. A file-based restore of Pub.edb and Priv.edb was performed from a recent production backup. The approach taken was to establish the production problem in a test environment. A server was built with the same organization and site name as in the production environment, but a different server name was used. The computer was also set up on a separate domain. This enabled a restore of an information store from a different computer (the production computer). Org=XYZ Site = NJ1 Server = SERVER2
Ran the following ISINTEG command: isinteg -patch | 5 minutes | After restore, the isinteg -patch command was used to complete an offline information store backup. The directory service and system attendant were started prior to running this command.
Started all Microsoft Exchange Services | 3 minutes |
Ran the DS/IS consistency adjuster | 5 minutes | The information store needed to be synchronized with the directory service on the test server because only the information store files had been restored, and not the directory.
Associated Windows NT account to test mailbox | 5 minutes | After the DS/IS consistency adjuster was used, a valid Windows NT ID needed to be assigned to a recovered mailbox. The Administrator program was used to associate the Windows NT account.
Tested messaging functionality | 10 minutes | Sent and received several messages in the Microsoft Exchange Client to test basic messaging functionality.
Ran Windows NT Ntbackup.exe program | 1.5 hours | Ran an online Ntbackup.exe job to test whether the production failure could be duplicated. At 1.5 hours, the information store backup failed 2.2 GB into the job, with an event ID 8010 error. This verified that testing was for a failing information store. The production problem was reproduced in a test environment with a copy of the production information store.
Stop Microsoft Exchange Services | 3 minutes |
Ran the following EDBUTIL command edbutil /ispriv /d /r /n | 2 hrs 30 minutes | Ran this command from the D:\Exchsrvr\Mdbdata directory to determine whether the corrupt information store could be repaired.
Ran the following ISINTEG command: Isinteg -pri -fix -verbose -l isinteg.log | 1 hr 10 min | Ran this command against the Priv.edb and Pub.edb files.
Start Microsoft Exchange Services | ~3 minutes |
Test Messaging | ~10 minutes |
Ran the Ntbackup.exe program again | ~2.5 hours | Performed another online backup to determine whether the problem still remained. The online backup of the information store and directory service completed successfully.


Backing Up a Key Management Server

It is recommended that you back up the KM server data files (for example, Security\Mgrent), separately from other data, and that you make sure these backup tapes more secure than your everyday backups. All keys in these files are 64-bit CAST encrypted, so this database is extremely secure. Remember that this database contains the private encryption keys for every user in your entire organization.

The problem with tape cartridges is that they are maintained offline. If someone were to steal one, that person could restore the files to his or her own server, and then try to crack the key used for the database, with no fear of detection due to online logons, and so on. For more information, see the Microsoft Exchange Server Administrator's Guide.


Disaster Recovery Frequently Asked Questions (FAQs)

This section provides answers to frequently asked questions regarding disaster recovery and Microsoft Exchange Server.

Q: If I have a good backup of the directory and information store and I am restoring a server to an existing site by reinstalling Microsoft Exchange Server, should I create a new site or join an existing site during the Microsoft Exchange Server installation?

A: Create a new site. Do not select Join Existing Site. If you attempt to join the existing site, an error will occur because other servers in the site already have knowledge of the server you are restoring. When the server is restarted after the restoration of the databases, the restored server automatically synchronizes with existing servers in the site, even though you selected Create a New Site during the server installation.

Q: If I want to keep a spare server online for performing single mailbox restores, should I select Join Existing Site or Create a New Site during the installation of Microsoft Exchange Server?

A: Do not select Join Existing Site. When maintaining a single mailbox restore server, you must configure the server with the same organization and site name as the site from which you plan to recover single mailbox data. However, it is important to repeat that you should not select Join Existing Site during the installation. Select Create a New Site. Also, use a unique computer name when installing Microsoft Windows NT. If you inadvertently join a site and then complete the single mailbox restore procedures as outlined earlier, undesired replication behavior will result after you run the DS/IS consistency adjuster because you will have two sets of mailbox data for the same users within the site after restoring a Priv.edb.

Q: I have some users that use .pst files and remain logged on at night. How can I back up their .pst files?

A: The client will automatically disconnect from the .pst file after 30 minutes of inactivity. Upon activity, the client will automatically reconnect to the .pst. Because of this feature, you can back up .pst files during periods of inactivity (usually at night) while the client is logged on to Microsoft Exchange Server.

Q: I know that I need to run isinteg -patch after restoring an offline information store backup to patch the globally unique identifiers (GUIDs), but what is a GUID?

A: A GUID is a 64-bit hexadecimal string. It uniquely tags an object in time and space. Within the information store, the private and public information stores have base GUIDs that they use to generate GUIDs for all other objects in the stores, including folders, messages, attachments, and so on. The patch that the ISINTEG tool performs changes the base GUIDs in the information store. The reason the patch must be run is because when you restore an information store, you are essentially rolling back time on that server. If you roll back the server and don't change the base GUID, new objects created in that information store could have GUIDs that are identical to other existing objects in the organization. This would cause problems in referencing objects, because they could no longer be uniquely identified. If you only have one server in your organization, this is not a problem, because when you restore, there are no other objects in the organization that have IDs that might be generated again for new objects.

Q: What is the tradeoff regarding location of log files? I have computers with a total of five disk drives. The first two drives are mirrored and the other three are set up in a RAID 5 stripe set? Should I not mirror the operating system and use one of those drives to dedicate for transaction log files to gain performance?

A: In Microsoft Exchange Server, the best performance is gained through dedicating a physical drive for transaction log files. This is because transaction log files are written to sequentially and on a dedicated drive, the disk read/write head will not have to contend with other processes. However, it may not be worth sacrificing operating system drive redundancy by not using a mirror set for the first two drives. In this case, it is best to maintain the Windows NT swap file and the Microsoft Exchange database files on the three-disk stripe set (RAID 5) and to maintain the transaction log files on the mirror set. With enough RAM in the system, there should be little disk head contention on the operating system drives and transaction log performance should be high.

Q: How important is transaction log file redundancy?

A: In general, transactions are committed to the databases quickly. However, on a very busy system, transactions written to log files can accumulate before being committed to the database files. If the transaction log drive crashes before transactions are written, this data will be lost.

Q: How can I shut down Microsoft Exchange Services without using Control Panel? Sometimes these services take a long time to shut down.

A: You can issue commands from the command line to shut down services or you can follow the batch file example shown below. If you want to shut down the entire system from a batch file, use the shutdown command, which is available on the Windows NT Resource Kit compact disc. The purpose of this command is to shut down services in reverse dependency order. To shut down an MTA service that includes spaces in the name, use quotation marks.

REM // stop all services

echo Stopping Services...

net stop MSExchangeMSMI

net stop MSExchangePCMTA

net stop MSExchangeFB

net stop MSExchangeDX

net stop MSExchangeIMC

net stop MSExchangeMTA

net stop MSExchangeIS

net stop MSExchangeDS

net stop MSExchangeSA

REM - call the shutdown command here. (Remember, this command requires that you have the Windows NT Resource Kit compact disc.)

Q: My tape drive is dead, but I need to back up the databases. How can I do this?

A: If you have enough disk space, shut down services and copy the Priv.edb and Pub.edb files from the Exchsrvr\Mdbdata directory (the default installation point). Also copy the Dir.edb file from Exchsrvr\Dsadata (the default installation point). You do not need to copy the transaction log files, because when services are shut down normally, all transactions are resolved. If you need to restore from this backup method, remove the log files and Edb.chk from their respective directories, copy the .edb files back in, and follow the procedure for running isinteg -patch. When the services start up, a new Edb.chk file is created, along with new transaction log files. Make sure to back up any files before you purge them. If you need additional assistance with these procedures, it is recommended that you contact Microsoft Technical Support.

Q: How long does it take to defragment a database using the EDBUTIL utility?

A: The databases are defragmented automatically as a background process, so unless the file size of the databases needs to be reduced, you should not have to run offline compaction (defrag with file size reduction).

Q: Do I need a backup of the directory database to recover a server?

A: You need at least one backup of the directory service for each computer. Regardless of how old the backup is, the directory service will rebuild itself on that computer and become current from the other directory services in the site after the restore. After you have installed a new server in a site and it is replicated and current, the best thing to do is to make a backup of the directory service.

After a restore, run a DS/IS consistency check after the directory service has came back in sync. This ensures that all objects in the information store on that computer are restored back into the directory service. If you don't have a backup of the directory service for a server to restore from, your only option is to delete the server from the site and then reinstall it. This option is not advisable because you lose all your information store data.

Instead, make a backup of the directory service as soon as possible after installing a new server, and then lock the backup in a safe place. Replace the backup with more up-to-date backups on a regular basis. This way, you don't have to wait long for the directory service to come back into sync after a restore.

Q: Why do I need to back up the system following the migration of users to the server? Also, why do I need to back up the system after running an offline EDBUTIL operation?

A: If a server crashes after a migration and you have not backed up the system data, you must perform the migration again. This can be time-consuming. After you run an offline EDBUTIL operation, the database is in a new state. If your system experiences a crash, you must perform the operation again. This can also be time-consuming.

Q: When I shut down services, they keep trying to restart. Why does this happen and what can I do?

A: This problem is most likely caused by a server monitor session configured for the server in which you are trying to shut down services. By running the Administrator program admin/t (maintenance mode) command at least one polling interval before stopping services, you ensure that the server monitor is notified that subsequent polls of the server in maintenance mode will not result in alerts or alarms. After running this command, you can stop services and perform maintenance. When the maintenance is completed, rerun admin /t to re-enable monitoring. For command-line Help on Administrator program command-line switches, switch to the Exchsrvr\Bin directory and type admin /?.

Q: What backup strategies and solutions are being created by third parties, and what value do their solutions add?

A: To learn more about third-party solutions, visit http://www.microsoft.com/exchange/exisv/. Then perform a search on all products that use the keyword "backup". This will provide links to third-party solutions.

Q: Is it a good idea to periodically perform a directory export ?

A: Yes. It is a quick operation and will save you time if you are unable to restore your directory database in the future. You should never have to rely on this procedure, but it is an extra safety measure that will enable you to quickly add users if necessary.

Q: Where can I find more information on information store startup problems?

A: Articles in the Microsoft Knowledge Base can be provide additional information on information store startup problems, and other issues. To access the Knowledge Base, visit http://www.microsoft.com/kb. Perform a search on "Microsoft Exchange," and then enter relevant keywords.

Q: What are "lazy" commits and "non-lazy" commits, and how does Microsoft Exchange Server use them?

A: After transaction logs are flushed to disk, the transaction is durable. If your system crashes, these logs can be restored and nothing will be lost. Non-lazy commits retain data on the hard drive, while lazy commits indicate that the transaction logs have not been saved.

Q: Should I disable the SCSI controller write cache?

A: Yes. Doing so enables you to avoid the potential for data loss. At a programming level, if the write through flag is set, Windows NT will not use buffers. Therefore, when a program receives a write complete signal from Windows NT, it is guaranteed that the write was completed to disk. This is critical to the Microsoft Exchange Server transaction logging process. If write cache is enabled, Windows NT thinks that a write has made it to disk and will inform the calling application of this "false" information. This could result in data corruption if a crash is experienced before this lazy write operation makes it to disk.

Q: When is a transaction committed to the database and how does this work? Is it first cached in memory so that it is virtually available, or is it necessary to read back from log files before writing to the database files?

A: Transactions are on both log files and fast memory pages. Log disk heads are never moved back to read old data, so only sequential writes occur on log files. After transactions are written to a log file, an operation is considered complete. The transaction is immediately available in server memory before it is actually committed to the database files. Remember that an operation is not complete (that is, the Client does not receive an acknowledgment) until all transactions are written to the transaction log (on disk).

Q: How can I measure how the transaction logging process is doing?

A: Use Performance Monitor and select the MSExchangeDB object. Configure the following counters:

  • Log Bytes Write/sec — The rate at which bytes are written to the log.
  • Log Checkpoint Depth — This is proportional to the time that recovery will take after a system crash, depending on the performance of the individual system. A data page may be cached and not flushed to the .edb file for a long time. The earliest logged operations on the page can date back a significant time. To ensure that your system recovers from a crash, do not restore too many logs, and set the checkpoint depth to determine how many logs you can expect to replay during recovery.
  • Log Sessions Waiting — The number of sessions waiting on a log commit in order to complete a transaction.

Q: What is the advantage of disabling circular logging?

A: Disabling circular logging provides for additional recoverability. This is because a history of transaction logs will be maintained for all transactions. These log files are only purged when a full or incremental online backup is performed.

They are purged because they are no longer needed after all transactions are committed to the databases and the databases are backed up. For example, suppose your last good backup occurred on Monday and on Thursday your database drive crashes. If you disabled circular logging and your transaction log files are configured on a separate physical drive from the drive that crashed, you can restore the Monday backup. In this case, you should not erase existing data, and you should verify that the log files created since the Monday backup have been restored back into the database. This process will restore your data to the point immediately before the crash.

Q: When I try to run the isinteg -patch command, it does not run and I receive the following error message: DS_E_COMMUNICATIONS_ERROR. How do I solve this problem?

A: Make sure the directory service is started before running the command.

Q: How can I back up Microsoft Exchange Server computers from a Windows NT Server backup computer that does not have Microsoft Exchange Server or the Microsoft Exchange Administrator program installed?

A: If you are copying files from an existing Microsoft Exchange Server computer, do one of the following:

  • In the Winnt Root\System32 directory on the Windows NT Server backup computer, rename or delete Ntbackup.exe.
  • From the Winnt Root\System32 directory on a Microsoft Exchange Server computer, copy the Ntbackup.exe, Edbbcli.dll, and Msvcrt40.dll files to the Winnt- Root\System32 directory on the Windows NT backup server.
  • From the Exchsrvr\Bin directory on the Microsoft Exchange Server computer, copy Edbback.dll to the Winnt Root\System32 directory on the Windows NT Server backup computer.

    Or, if you are copying files from the Microsoft Exchange Server compact disc:

  • In the Winnt-Winnt-Root\System32 directory on the Windows NT Server backup computer, rename or delete the Ntbackup.exe file.
  • From the Setup\<platform> directory on the Microsoft Exchange Server compact disc, copy the Ntbackup.exe, Edbbcli.dll, Edbback.dll, and Msvcrt40.dll files to the Winnt-Root\System32 directory on the Windows NT Server backup computer.

Q: Do I need to run the DS/IS consistency adjuster after restoring the directory and information store?

A: No. You only need to run the DS/IS consistency adjuster if you can only restore the information store. The consistency adjuster scans the information store and ensures that a directory service object exists for each information store object. If not, the directory service object is created. The consistency adjuster also scans the directory service and ensures that a corresponding information store object exists. If it does not, the directory service object is deleted. Finally, the consistency adjuster also verifies the access control list (ACL) for each object and strips any invalid entries from the list. You can also set the DS/MDB Sync diagnostic logging level to maximum and then check the application log.

Q: Should I avoid running the DS/IS consistency adjuster?

A: If you only restore the information store and must run the DS/IS consistency adjuster to re-create the directory service object for the mailboxes in the store, this sets the HOME-MDB attribute on all public folders in the hierarchy (replicas or not) to this server . In addition, it strips the public folder ACLs of any invalid entries (that is, users who do not exist in the current directory).

If you do this and then re-create a replication connector into the organization, there will be a conflict. The new server will probably win the conflict because it has newer changes to the public folder property. Accordingly, the public folder will be homed on the new server, and the new server's ACL will most likely be the ACL that is kept. This will result in lost permissions for some users.

Q: I cannot find the backup set on my tape. What might cause this?

A: Make sure that you catalog the tape before restoring any data. This process enables you to gather information on the files available on the tape, and it enables the restore process to take place. After the catalog is completed, you can start the restore process. To load a catalog of the backup sets on a tape:

  • In the Tapes window, select the tape whose catalog you want loaded.
  • Choose Catalog in one of three ways: Double-click the icon for the appropriate tape, or choose the Catalog button, or choose Catalog from the Operations menu.

    After you search the tape, a complete list of backup sets appears in the Tapes window. Question marks are displayed in each icon to indicate that their individual catalogs have not been loaded.

Q: If you delete and re-add a computer name to the domain, and then restore the Windows NT registry from tape, is it true that the local SID from the restored Windows NT registry will not match the new SID created in the domain?

A: Yes. You should delete and re-add the name of a Microsoft Exchange Server computer in the domain only if a new server is required for recovery. The Windows NT registry should only be restored to the same physical computer because the Windows NT registry contains computer-specific data. This situation may occur if only the operating system hard disk was replaced and a Windows NT restore is performed.

Another issue to consider is that the Microsoft Exchange Server directory database maintains information about Windows NT IDs in the domain, such as ACL information. If you cannot access the SAM from the original domain and you create a new SAM by installing a new domain, and then restore the directory service, you will have a disconnect between the object security in the directory service (such as the Microsoft Exchange service account, user mailboxes, and administrator's account) and the new domain SAM. As a result, you will not be able to access any object in the Microsoft Exchange Server directory.

Q: What is the impact of configuring Microsoft Exchange Server computers as BDCs?

A: Configuring Microsoft Exchange Server computers as BDCs can provide increased recoverability and reduced costs. However, the memory requirements for these computers are also increased.

For example, suppose that a Microsoft Exchange Server computer configured as a PDC needs to be replaced. Although the Windows NT domain controller can be rebuilt and the information store can be restored, but the directory service cannot be successfully restored to a domain that does not have the original SAM.

Q: Does a full server restore to a different physical computer require the recovery server to be configured as a BDC or PDC?

A: No. The important thing is that the computer account is deleted and then re-added to the production domain so that the recovery computer can obtain a new SID that uses the same name as the original production server.

Q: How do you compact the information store databases?

A: Microsoft Exchange Server automatically compacts the information store and directory databases without interruption to messaging. Online compaction takes place in the background, marking items for deletion and defragmenting the database files.

You can also use the EDBUTIL utility to compact the information store databases. Running the EDBUTIL /D command reduces the size of the information store database files and defragments the database. In contrast, online compaction defragments the database files, but does not decrease their size. Note that if you use the /D (defragment) command-line option when running EDBUTIL, you must first stop the information store service.

Q: What is the difference between compaction, defragmentation, and information store maintenance?

A: By default, information store maintenance occurs between 1:00 a.m. and 6:00 a.m. The following tasks are typically completed during information store maintenance: tombstone compression, column aging, index aging, clean per user read, and message expiration. To view these settings from within the Microsoft Exchange Administrator program, select the appropriate server under Org, Site, Configuration. Choose Properties from the File menu, and then select the information store Maintenance tab.

Compaction is the the process of online defragmentation and reclaim of disk space.

Defragmentation is the offline process of reclaiming disk space and defragmenting the database files. Defragmentation is accomplished through the EDBUTIL /D command and will reclaim space, as well as reduce the size of the database files.

Q: At what point do log files wrap around when database circular logging is used?

A: This is usually kept to four files, but if there is a heavy load on the server, such as during a large import/migration operation or a public folder backfill, the checkpoint and window will grow greater than four log files. This does not decrease until the information store or directory service is stopped and then restarted. After the respective services are stopped and restarted, the window returns to four log files.

Q: What is the Temp.edb file and why does it get created?

A: If long-term transactions are taking place, the Temp.edb file is used to store transactions that are in progress. This file is also used for transient storage during online compaction.

Q: When should the edbutil /d /r command be used?

A: Only as a last resort should you use this command to repair databases. Note that this command can delete data. Before running Edbutil /d /r, you should always attempt a restore.

Q: What are the Res1.log and Res2.log files used for?

A: These are reserve log files that are not used unless the transaction log hard disk fills up. They are reserved for transactions that may be required to shut down the information store if the disk fills up. This way, even if the hard disk fills up, there is reserved space to record transactions from memory to disk. Note that these files are 5 MB each, regardless of the number of transactions in the log files.

Q: If an information store is in recovery after a system crash, will Microsoft Exchange Server be smart enough not to duplicate preexisting transactions in the database and only play back uncommitted transactions?

A: Yes. Log files are read and this is a very fast operation. If the transaction version number is already in the database, the transaction will not be recommitted.

Q: Will Microsoft Exchange Server automatically play back uncommitted transactions from logs when the services come up the first time following a crash?

A: Yes. If the database shut down was not clean, Microsoft Exchange Server records that and replays all transactions from the checkpoint forward at startup.

Q: If circular logging is enabled, is it true that you cannot play back logs (those that are present within the circular window)?

A: Yes. With circular logging enabled, you cannot restore from a backup and play forward. You can only restore from backup at the point the backup was taken. By default, Microsoft Exchange Server is configured with circular logging enabled.

Q: If circular logging is disabled, how can you play back transaction log files if required?

A: With circular logging disabled, you can play back logs from the last full backup. It will depend on how you are performing backups. For example, suppose that you perform a full weekly backup on Sunday and incremental backups Monday through Saturday. If you lose a hard drive or other data on Thursday, you need to restore tapes in the following order:

  • Sunday: Full restore. Don't start services.
  • Monday: Incremental restore. Don't start services.
  • Tuesday: Incremental restore. Don't start services.
  • Wednesday: Incremental restore. Don't start services.

After these restore operations are completed, start the information store service. Note that you can restore all of these backup sets in one job, and then select Start Services after the restore. When you do so, Ntbackup.exe will not start services until the files from all sets are restored. Ntbackup.exe will restore the data and log files from Sunday, and add the log files for Monday through Wednesday when the services restart. Finally, Ntbackup.exe will replay all log files from after the point of the full backup on Sunday until the present time (that is, Monday through Wednesday, plus any log files created after the Wednesday backup).

Incremental backups delete log files after a backup is completed. Differential backups do not delete log files; instead these files are written to tape. If you were performing differential backups, you would not need to restore the Monday through Wednesday backup because you would still have those log files on the system.

Incremental and differential backups back up all log files since the last backup, as well as the Edb.chk file. The difference between these two backup types is that differential backups do not delete log files from the system.

Q: What is the difference between running the isinteg - fix command and the edbutil /d /r command?

A: The edbutil /d /r command should only be run as a last resort in order to repair a database file. The isinteg - fix command repairs high-level objects, while edbutil /d /r repairs low-level database corruption. The isinteg - fix command repairs any "scheme" and other high level data/structure problems. If you need to run both commands, run edbutil /d /r first and then run isinteg - fix. Note that you should only run both commands if you don't have a backup to restore from and log files to play forward.

Restoring data from a backup and then playing logs forward is the recommended way to restore a corrupted database due to hardware failure. These procedures are recommended because they enable you to recover all your data. If you do not have a backup to restore and run the edbutil /d/r and isinteg - fix commands instead, you will lose all your data.

Q: Can Microsoft Exchange Server perform information store compression on the fly? Should administrators perform manual compression on a periodic basis?

A: Microsoft Exchange Server can perform online compaction, which is different than compression.

Microsoft Exchange Server reuses the space before growing the file. So, database defragmentation takes place in the background on a running server. The only time you should have to shut down a server for offline compaction is if you want to physically recover the free space on the disk. To reduce .edb file size, stop Microsoft Exchange services and then run the edbutil /d command.

Q: What is the purpose of log files?

A: On a Microsoft Exchange Server computer, the public information store, private information store, and the directory service each have log files. These files are the transaction logs for all transactions that occur on the database. In the event of a system crash, hard drive failure, power failure, or another disaster, these files can be used for soft and hard recovery and for restore after backup. The Priv.edb file on a running server is always inconsistent, due to the database cache that is in RAM on the server. The consistent state of a server is made up of the data in the .edb file and the data in the memory cache on the server. If a server computer crashes and you don't replay the logs, this will result in a corrupt database.

The log files permit automatic playback of transactions that have occurred on the database but are not yet committed to the .edb file. There is a check point (Edb.chk) that contains the current transaction point in the log files that have been committed to disk.

Log files continue to consume disk space until you do one of the following:

  • Back up the server (by performing a full backup or an incremental backup). This writes all logs to the tape up to the check point and then deletes the logs written to tape from the hard drive. If you have to restore the database, the backup copies the database file from the tape, replays the logs on the tape, and then replays all the logs on the disk.
  • Run with circular logging enabled.

If you browse the .edb file directories, note that you will also see *.pat files. These files are created when a backup is performed and contain all the changes (patches) since the backup started. You can write the patch file when performing a backup and be completely current. The following table lists files that you would see in the Exchsrvr\Mdbdata directory.

File | Description
Priv.edb | Private database file.
Pub.edb | Public database file.
Edb.log | Current latest log file being written to.
Edbxxxxx.log | Previous log files no longer opened or being used; new .log file every 5 MB.
Res1.log Res2.log | Two log files are reserved in case the database or log file drive fills up the server.
Priv.pat | Backup patch file for Priv.edb.
Pub.pat | Backup patch file for Pub.edb.
Edb.chk | Checkpoint file.


Monitoring Disk Space

An administrator can observe disk space usage on the drive containing the information store by using the Windows NT Performance Monitor. The LogicalDisk object, along with the "% Free Space" and "Free Megabytes" counters, are used to monitor and trigger alerts when disk space is low.


Recovering Space Used by Log Files

Increasing log files can cause the information store or directory to run out of operating space. To prevent this, do one of the following:

  • Write the log files to a different drive.
  • Change the location where the information store or directory store transaction logs are written. To do so, select the server object. From the File menu, choose Properties, and then select the Database Paths tab. Change the path names for the information store and directory transaction logs, and then choose OK.
  • Back up the Microsoft Exchange Server computer.
  • Use Ntbackup.exe to perform a normal (full) or incremental online backup of the server. This utility automatically deletes transaction logs that are no longer needed (they have been committed to disk). If you do not run Ntbackup.exe, the log files will continue to grow.
  • Circular logging writes log files, but after the checkpoint has been advanced, the inactive portion of the transaction logs are discarded. Typically, this represents the majority of the potential log data. The total size of the active transactions are less than the total amount of RAM on a given computer. Therefore, with circular logging enabled, the system has complete recoverability with respect to hard and soft crashes. The element that is sacrificed is the protection against media failure. These methods are not supported on servers where circular logging is enabled, because the transaction logs are used for incremental and differential backups.
  • If possible, delete any sample applications to free additional disk space.

Q: Why do I need to run the isinteg -patch command after running an offline information store restore and before starting the information store service?

A: To guarantee that GUIDs are unique. If a copy of the information store (Pub.edb and Priv.edb) is restored from an offline backup and isinteg -patch has not been run, when the service is restarted, it will fail, and a -1011 error will be generated. The -1011 error will produce an entry in the Windows NT Event Viewer Application Log with source ID 2048. The error message will read as follows:

The information store was restored from an offline backup. Run isinteg -patch before restarting the information store.

This error occurs because the GUIDs used by the information store that was restored are old and matching GUID may already exist. The GUID for this restored information store needs to be replaced to ensure that it is unique.

A command prompt error ("DS_E_COMMUNICATIONS ERROR") will also appear.

Procedure for patching the information store

To replace the GUIDs used by the restored information store, you need to run isinteg -patch. This command enables the ISINTEG utility to run in patch mode against the entire information store (Pub.edb and Priv.edb) and generate new GUIDs. Replication information will also be patched to prevent incorrect backfilling.

To run the isinteg -patch command, do the following:

  • Ensure that the directory and system attendant services are running. If these services are not running, ISINTEG will fail (with a DS_COMMUNICATIONS_ERROR message).
  • At the command prompt, switch to the Exchsrvr\Bin directory, and then type isinteg -patch.

The GUIDs will be replaced and the ISINTEG will report that the information store has been updated. At this point, you need to restart the information store service.

Q: When restoring a server in a site, if I do not have a backup of the directory (Dir.edb) for the server, can I backfill the directory from a replica on another server in the site?

A: No. It is critical that you have a backup of the directory for each Microsoft Exchange Server computer because the directory is unique for each computer. Even if you only have the original directory backup, you can restore this backup and then backfill changes from another server in the site.

Q: What is the Microsoft Exchange Server setup /r command used for?

A: The setup /r command enables recovery of an existing Microsoft Exchange Server computer to new hardware. Restoration of a valid database backup is also required. Run the setup /r command when you want to move a server installation to a different computer or if you are restoring data to a new computer.

The figure below shows the message that appears when you run the setup /r command.

Q: Is a differential backup required only when both the transaction drive and the .edb drive need to be recovered?

A: Yes. If circular logging is disabled and the transaction logs are intact, you can restore the last full backup. When the service is started, logs from the point of the full backup will be played through the current Edb.log file to bring the database up-to-date. In this case, do not select Erase all existing data during the restore, or the transaction logs will be erased and you will need to restore the differential tape.

Q: Why can't I start services between restoring a full tape and a differential or incremental tape, or between sequential tapes being restored?

A: This is because at the end of a restore, Microsoft Exchange Server plays back all logs in sequential order. After this is done, the database is set to a new state. For example, if the services are started between a Monday incremental tape restore and a Tuesday incremental tape restore, a new state will be set. When you attempt to perform the Tuesday incremental restore, the restore will not be possible because the state of the database is expected to be exactly what it was at the point of the Tuesday backup. This behavior prevents overwriting new operations that have occurred on the database after services have been started.


Command-Line Switches for Ntbackup.exe

When you want to back up your files manually, you can use command-line switches with Ntbackup.exe.

Note In a batch file, limit the command line to 256 characters. Exceeding this limit may result in files not being backed up and may stop the process without warning.

The syntax for this command is as follows:

Ntbackup operation path [/a][/v][/r][/d"text"][/b][/hc:{on | off}] [/t{option}][/l"file name"][/e][/tape:{n}]

Switch | Description
Operation path | If you are backing up a drive, specifies one or more paths of the directories to be backed up. If you are backing up Microsoft Exchange Server components, specifies the component and the server as {directory service server /information store server}. Server is the name of the server you are backing up, preceded by two backslashes. Directory service indicates that you are backing up the directory, and information store indicates that you are backing up the information store.
/a | Causes backup sets to be added after the last backup set on the tape. When /a is not specified, the program reuses the tape and replaces previous data. When more than one drive is specified but /a is not, the program overwrites the contents of the tape with the information from the first drive selected and then appends the backup sets for the remaining drives.
/v | Verifies the operation.
/v /r | Restricts access.
/d "text" | Specifies a description of the backup contents.
/b | Specifies that the local registry be backed up.
/hc:on or /hc:off | Specifies that hardware compression is on or off.
/t {option} | Specifies the backup type. Option can be one of the following: normal, copy, incremental, differential, or daily.
Normal | All selected files or Microsoft Exchange Server components are backed up and marked as such on the disk.
Copy | All selected files or Microsoft Exchange Server components are backed up, but they are not marked as such on the disk.
Incremental | Among the selected files or Microsoft Exchange Server components, only those that have been modified are backed up and marked as such on the disk.
Differential | The selected files or Microsoft Exchange Server components that have been modified are backed up, but are not marked as such on the disk.
Daily | Among the selected files, only those that have been modified the same day are backed up, but they are not marked as such on the disk. This can be useful if you want to take work home and need a quick way to select the files that you worked on that day. This option is not available when backing up Microsoft Exchange Server components.
/l "file name" | Specifies the file name for the backup log.
/e | Specifies that the backup log include exceptions only.
/tape:{n} | Specifies the tape drive to which the files should be backed up. N is a number from zero to nine that corresponds to the tape drive number listed in the registry.


EDBUTIL

EDBUTIL is a utility that can be used to maintain Microsoft Exchange Server databases. The modes of operation for this tool are outlined below.

Operation | Syntax
Defragmentation | Edbutil /d <database name> [options]
Recovery | Edbutil /r [options]
Consistency | Edbutil /c <database name> [options]
Backup | Edbutil /b <backup path> [options]
Upgrade | Edbutil /u <database name> /d<previous .dll> [options]
File dump | Edbutil /m[mode-modifier] <file name>


Defragmentation and Compaction

You can use the EDBUTIL utility to defragment and compact the data on your hard drive.

To perform an offline compaction of a database, use the following syntax: edbutil /d <database name> [options]

Option | Description
<Database name> | File name of database to compact, or one of the following: /ispriv, /ispub, or /ds
Options | Zero or more of the following switches, separated by a space: /l<path> - location of log files (default is the current directory).
/s<path> | Location of system files.
/r | Repairs database while defragmenting.
/b<db> | Creates backup copy under the specified name.
/t<db> | Sets the temporary database name with a default name of Tempdfrg.edb.
/p | Preserves temporary database
/n | Instructs the program to dump defragmentation information to the Dfrginfo.txt file.
/o | Suppresses the logo.

The /ispriv, /ispub, and /ds switches use the registry to automatically set the database name, log file path, and system file path for the appropriate Microsoft Exchange Server store (public or private). Before defragmentation begins, soft recovery is always performed to ensure that the database is in a consistent state. If you disable instating by using the /p switch, the original database is preserved uncompacted, and the temporary database will contain the defragmented version of the database.


Recovery

Recovery is a utility that brings all databases to a consistent state. This utility is used in conjunction with EDBUTIL. The correct syntax is edbutil /r [options].

Switch Option | Description
/is or /ds | The /is and /ds switches use the registry to automatically set the log file path and file path for recovery of the appropriate Microsoft Exchange stores (public or private).
/l<path> | Location of log files.
/s<path> | Location of system files.
/o | Suppresses the logo.


Consistency

To verify the consistency of a database, you can use the EDBUTIL utility with specific switches. The correct syntax is edbutil /c <database name> [options]. The options are zero or more of the switches as detailed in the table below. The switches must be separated by a space.

Switch Option | Description
<Database name> | File name of database to verify, or /ispriv, /ispub, or /ds.
/a | Checks all nodes, including deleted nodes.
/k | Generates key usage statistics.
/p | Generates page usage statistics.
/t<name> | Performs a check on the specified table only (default: checks all tables in the database).
/o | Suppresses the logo.

The consistency checker performs no recovery and always assumes that the database is in a consistent state. If the database is not in a consistent state, an error message is returned. The /ispriv, /ispub, and /ds switches use the registry to automatically set the database name for the appropriate Microsoft Exchange Server store (public or private).


Upgrade

You can upgrade a database that was created using a previous release of Microsoft Exchange Server to the current version. The correct syntax for performing this function is edbutil /u <database name> /d<previous .dll> [options].

Note This utility should only be used to upgrade a database after an internal database format change has occurred.

The following table is a list of the parameters and options to use with EDBUTIL when upgrading a database. For options, you can use zero or more of the switches, separated by a space.

Parameters and Options | Description
<Database name> | File name of the database to upgrade.
/d<previous .dll> | File name of the .dll file that came with the release of Microsoft Exchange Server from which you are upgrading.
/b<db> | Makes a backup copy under the specified name.
/t<db> | Sets the temporary database name with a default name of Tempupgd.edb.
/p | Preserves the temporary database indicating not to instate.
/n | Dumps the upgrade information to a file called Upgdinfo.txt.
/o | Suppresses the logo.

Before you upgrade the database, the database should be in a consistent state. If the database is not in a consistent state, an error message will be returned. If you disable instating by using the /p switch, the original database is preserved unchanged, and the temporary database will contain the upgraded version of the database.


File Dump

The File Dump utility generates formatted output of various database file types. The correct syntax for using this utility is edbutil /m[mode-modifier]
<file name>.

Parameters and Switch Options | Description
[mode-modifier] | An optional letter designating the type of file dump to perform. Valid values are: h (dump database header) and k (dump checkpoint file).
<file name> | The name of file to dump, where the type of the specified file should match the dump type being requested.


ISINTEG

The ISINTEG utility is a Microsoft Exchange Server information store integrity checker. The correct syntax for using this utility is:
isinteg -pri|-pub [-fix] [-verbose] [-l log file name] [-test test name,...]

The following table describes the switch options, parameters and their description.

Parameters and Options | Description
-pri | Private information store
-pub | Public information store
-fix | Check and correct, with check only as the default.
-verbose | Report verbosely.
-l file name | The default file name is \isinteg.pri|pub.
-test test name | The default is all tests.
Folder message | aclitem
Mailbox message | delfld acllist rcvfld timedev rowcounts
Attach message | morefld oofhist peruser
Attach global | searchq dlvrto namedprop
Ref count tests | msgref attachref acllistref aclitemref fldrcv fldsub
Special tests | deleteextracolumns (not included in all)
isinteg -patch | Repair information store after an offline restore.
-patch () | isinteg -pri|-pub -dump [-l logfilename] (verbose dump of store data)


Server Configuration Sheets

The following tables illustrate examples of server configuration sheets that you can use when setting up your hardware and software specifications.

Hardware Configuration

You can use the following hardware table when specifying hardware requirements for your organization.

Hardware Item | Description
Computer Model |
Display Model |
S/N |
BackPlane |
CPU |
Hard Disk(s) |
Floppy Disk |
RAM |
NIC |
SCSI Card |
CD-ROM |
Tape Backup |

Windows NT Installation Configuration

You can use the following Windows NT installation table when specifying requirements for your organization.

Item | Description
Windows NT Server Version |
Windows NT Server Role |
Domain Name |
Computer Name |
Install Director |
Swap File |
Protocols |
Disk Configuration |
Licensing |
Printer |
Special Groups |
This Machine IP |
Subnet Mask |
Default Gateway |

Microsoft Exchange Server Installation

You can use the following table when specifying Microsoft Exchange Server requirements for your organization.

Item | Description
Org Name |
Site Name |
Computer Name |
Service Account |
Service Account Password |
Connectors |

Microsoft Exchange Performance Optimizer

Running the Microsoft Exchange Performance Optimizer is important during recovery to ensure that the recovery server is tuned properly. Hardware being equal, similar performance can be experienced following a full restore where Microsoft Exchange Server is reinstalled to a recovery server. Note that the Performance Optimizer log stored in the Winnt35\System32 directory does not expose the specific settings that were chosen during optimization.

Server Name: ________________________

Estimated Number of Users | X | Type of Server | X | Number in Organization | X | Limit Memory Usage
1 to 25 |  | Private information store |  | Less than 100 |  | ____MB
26 to 50 |  | Public information store |  | 100 to 999 |  |
51 to 100 |  | Connector/directory import |  | 1,000 to 9,999 |  |
101 to 250 |  | Multiserver |  | 10,000 to 99,999 |  |
251 to 500 |  |  |  | 100,000 or more |  |
More than 500 |  |  |  |  |  |

Component Locations

The following table lists the name s of Microsoft Exchange Server components and their locations.

Component | Location
Private information store | Exchsrvr\Mdbdata
Public information store | Exchsrvr\Mdbdata
Information storelLogs | Exchsrvr\Mdbdata
Directory service | Exchsrvr\Dsadata
Directory service logs | Exchsrvr\Dsadata
Message transfer agent | Exchsrvr\Mtadata
Internet Mail Service | Exchsrvr\Imcdata

Additional Information Sources

Following are sources of additional information on planning or maintaining a disaster recovery plan in your organization.

  • For updates to the information in this chapter, visit: http://www.microsoft.com/exchange/evalgd.htm
  • To view Microsoft Exchange Deployment Conference papers online, visit: http://www.microsoft.com/exchange/presentations.htm
  • Microsoft TechNet: (800) 344-2121; technet@microsoft.com
  • Microsoft Knowledge Base: http://www.microsoft.com/kb/
  • Microsoft Knowledge Base Article Q154792: "Exchange and Schedule+ White Papers and Their Locations."
  • Microsoft Knowledge Base Article Q155269:"Microsoft Exchange Administrators' FAQ."
  • Microsoft Exchange Server Administrator's Guide (Chapter 15)
  • Microsoft Exchange Server Concepts and Planning Guide
  • Microsoft Exchange home page: www.microsoft.com/Exchange/
  • Public Listserver (not maintained by Microsoft):
    E-mail msexchange-request@insite.co.uk with the word SUBSCRIBE in the message body.
    Note that this list will generate several dozen messages per day.
  • Public Listserver (not maintained by Microsoft):
    E-mail msexchange-digest-request@insite.co.uk with the word SUBSCRIBE in the message body.
    You will receive one long message each day with postings from that day.
  • MSNEWS network news transfer protocol (NNTP) server: msnews.microsoft.com
  • Microsoft Press® Books (MSPRESS): United States (800) MSPRESS;
    Canada (800) 667-1115
  • Microsoft Consulting Services (MCS): U.S. (800) 426-9400;
    Canada (800) 563-9048
  • Microsoft Solution Provider Program: (800) SOLPROV
  • National Computer Security Association: http://www.ncsa.com


Chapter 5 Application Development

This chapter describes how you can develop custom Microsoft Exchange Server solutions to make business communications easier. The following topics are discussed:

  • The scope of applications that can be developed.
  • The role each component plays in providing these solutions.
  • The capabilities of each component, demonstrated through customer scenarios.

Applications range from those that can be created by novice users modifying existing sample applications, to complex groupware applications developed with high-end development tools such as the Microsoft Visual Basic® programming system and the Visual C++® development system.


The Microsoft Exchange Server Infrastructure

Microsoft Exchange Server provides application development capabilities within an easy-to-administer infrastructure for messaging and replicated databases. This infrastructure includes the following components:

  • Microsoft Exchange Server — Includes client and server software, including the directory service, information store, Message Transfer Agent (MTA), and System Attendant.
  • Microsoft Exchange Client — Includes clients for the MS-DOS®, Windows® 3.1, Windows NT Workstation, and Windows 95 operating systems. These clients enable users to find the important information, structure it in a meaningful way, and build common information-sharing solutions without relying on the information services (IS) department.
  • Microsoft Outlook™ Client — Includes clients for the Windows NT Workstation and Windows 95 operating systems. The Outlook client is a desktop management system that integrates messaging, scheduling, contact, task and file management into one environment.
  • Microsoft Schedule+ — Makes it easy to organize meetings, resources, tasks, and contact information, and provides a programmatic interface for integrating these capabilities into custom solutions.
  • Microsoft Exchange Forms Designer — A Microsoft Windows-based forms-design capability that enables users to develop forms-based applications for Windows without programming, and generates Visual Basic source code for additional customization.
  • Microsoft Exchange Server sample applications — Provide examples and source code for three categories of applications:
    • Applications designed with the tools available in Microsoft Exchange Server.
    • Customized Visual Basic–based applications integrated with Microsoft Exchange Server.
    • Server applications that run as a service of Windows NT Server and can be integrated with Microsoft Exchange Server.
  • The MAPI subsystem — Microsoft Exchange Server is built on an open, widely used set of messaging application programming interfaces known as MAPI. These programming interfaces enable developers to use tools such as OLE Messaging (an OLE Automation interface to MAPI) OLE Scheduling (an OLE Automation interface to Schedule+), and MAPI itself.


Understanding the MAPI Subsystem

The following diagram shows the MAPI subsystem infrastructure on which Microsoft Exchange Server is built.

Messaging client applications either communicate with service providers through the MAPI subsystem, or the MAPI subsystem initiates contact and the services communicate directly. Through broad publication of messaging APIs, and their robust messaging and workgroup functionality, MAPI has become a widely used standard throughout the industry for messaging and groupware clients and providers.

As the previous diagram shows, MAPI-compliant clients span a variety of messaging- and workgroup-based applications and support either 16-bit applications running on Windows 3.x, or 16-bit or 32-bit MAPI applications running on Windows NT Server or Windows 95. Each of these types of applications can access the service provider functionality needed without requiring a specific interface for each provider. This is analogous to applications that use the Microsoft Windows printing subsystem not requiring drivers for every available printer.

Messaging applications that require messaging services can access them through any of five MAPI subsystem interfaces:

  • Simple MAPI (sMAPI)
  • Common Messaging Calls (CMC)
  • OLE Messaging/Active Messaging
  • OLE Scheduling
  • MAPI itself

Client requests for messaging services are processed by the MAPI subsystem—either as function interface calls (for sMAPI or CMC) or as manipulations of MAPI objects (for OLE Messaging or MAPI itself)—and are passed on to the appropriate MAPI-compliant service provider. The MAPI service providers then perform the requested actions for the client and pass the action back through the MAPI subsystem to the MAPI client.

Each MAPI subsystem interface provides specific functionality as follows:

  • sMAPI — Contains 12 Windows-based function calls that enable messaging-aware applications to perform basic messaging tasks such as sending e-mail and resolving conflicts in e-mail names. It provides the programming interface primarily used by Microsoft Mail Server.
  • CMC — Provides functionality similar to that available in sMAPI but also supports cross-platform configurations.
  • OLE Messaging — An OLE Automation server that presents a large subset of MAPI functionality to the developer. OLE messaging empowers developers using Visual Basic or Visual Basic for Applications to tap into the messaging and workgroup functionality inherent in MAPI. It also permits users to maximize their software investment, by integrating applications created with Visual Basic for Applications and desktop software into custom Microsoft Exchange Server solutions.
  • OLE Scheduling — An OLE Automation server that provides developers who use Visual Basic or Visual Basic for Applications with an interface to access the information stored in Microsoft Schedule+ 7.0.
  • MAPI — A Component Object Model (COM) interface that enables MAPI objects such as messages, forms, and folders to be manipulated. It was designed to be used by complex messaging and groupware applications. For this reason, MAPI is used by developers who want the full range of MAPI functionality in their applications and the higher performance of writing directly to an API.

Not shown in the preceding diagram, but frequently employed, are third-party programming interfaces that can be built upon MAPI. Because MAPI is an open and well-defined interface, a proprietary third-party API can be implemented on top of MAPI without having to revise the MAPI subsystem itself. You can also implement your own MAPI solutions to meet your particular needs without incurring the development costs that would otherwise accrue on other messaging infrastructures.


Integrating Schedule+ Applications

In addition to the MAPI interfaces, Schedule+, a key component available with Microsoft Exchange Client, includes an OLE Automation interface known as OLE Scheduling. Developers using Visual Basic and Visual Basic for Applications can readily integrate Schedule+ into their applications.

For example, you can use the telephony application programming interface (TAPI) and Schedule+ to create an application that sends Schedule+ meeting reminders, including a text message, to a user's pager. Or, using Microsoft Project, tasks can be scheduled in both Microsoft Project and Schedule+.

Tight integration between Microsoft Office for Windows 95 and Schedule+ enables you to quickly build applications that integrate that suite of applications, by using Visual Basic for Applications through the OLE Scheduling interface. For example, you can create an application that enables new contact information entered into Schedule+ by a company's sales force to be copied to Microsoft Excel for reporting and analysis, and reports to be generated in Microsoft Word based on information in Schedule+.


Building a Range of Solutions on a Single Platform

Most organizations need a wide range of business applications to improve processes and respond to competitive opportunities. In many organizations, this results in a heterogeneous collection of operating systems, e-mail systems, security platforms, and user directories, and the corresponding overhead of supporting those systems, training users on a variety of interfaces, and hiring a development staff versed in a wide array of technologies.

By providing an extensible messaging platform upon which users can access and build messaging and groupware, Microsoft Exchange Server eliminates the need for duplicating security systems, user directories, client interfaces, systems management interfaces, and development technologies that often accompany process-automation solutions. Microsoft Exchange Server doesn't require its own security system; it simply uses that of the operating system.

Because Microsoft Exchange Server is built on MAPI, custom-application developers and third-party software developers can write to a powerful, widely accepted programming interface to provide customers with a wide selection of groupware applications. By bringing these components under the control of a single messaging-based platform, organizations can focus their resources on creating customized applications, rather than on managing the complexities of multiple and often incompatible systems for each type of messaging or workgroup application.


Factors to Consider When Automating Business Processes

Most organizations recognize the importance of automating business processes. But most organizations must also consider a number of fundamental questions before they can determine what processes should be automated and how to automate them. These considerations include:

  • What kind of applications do my users need?
  • What are the associated development costs?
  • What if I want to add custom functionality to those applications?


Building Common Groupware Applications

Building applications on a messaging server goes well beyond simply sending rich-text notes with attachments. Microsoft Exchange Server includes built-in groupware for routing, discussion, reference, and tracking applications. Microsoft Exchange Server also supports highly customized groupware applications and can even be integrated into customized desktop or Microsoft BackOffice server applications. The following sections describe typical groupware applications supported natively by Microsoft Exchange Server.

Routing Applications

Microsoft Exchange Server enables end users to easily create person-to-person routing forms. For example, a sales manager can design a form to gather weekly sales data from salespeople. Any salesperson, whether connected to the network or mobile, can fill out the pre-addressed form and send it back to the sales manager.

Discussion Applications

Microsoft Exchange Server also supports discussion, or bulletin board applications. These applications enable users to discuss topics with their co-workers through public folders, rather than carrying out conversations over e-mail and wading through their Inbox to find relevant e-mail threads.

Reference Applications

Most organizations need a central repository where users can find information. Microsoft Exchange Server replicated public folders provide a useful infrastructure for this type of application. Employee handbooks, product information, monthly reports, and sales data are all examples of useful information that can be published in public folders.

You can also make Internet newsgroups easily accessible to public folder users by developing applications for the Microsoft Exchange Internet Mail Service and the Internet News Service.

Tracking Applications

In most organizations, salespeople need to access information sources before making an account call. They may need to call other salespeople to determine who last contacted the customer, or review sales orders to find out whether the customer has outstanding orders. Many organizations provide this functionality through third-party products. Microsoft Exchange Server tracking applications eliminate this complexity and bring tracking functionality under the same user interface as other groupware applications.

For example, by creating a customer-tracking public folder, a salesperson can find information on the last contact with the customer, new customer contacts, and the company profile in a single location.

Microsoft Exchange Client enables salespeople to customize the way they display data, to view the information in the same interface as other Microsoft Exchange Server applications, and to use custom forms designed with Microsoft Exchange Forms Designer to organize and report the information. The following figure illustrates a customized view that enables users to view account data by company.


Cutting Development Costs

Competitive pressures dictate that organizations must find ways to reduce the time it takes to complete processes and access information. As a result, organizations are constantly building custom workgroup solutions. Organization-wide workgroup solutions are typically built by professional software developers who are part of the IS department. At the departmental level, solutions are often developed by technical "power users" who have learned how to write programs.

Both of these development resources are expensive, and so are the solutions they provide. Because custom solutions are in high demand, IS departments are overwhelmed with requests for new software systems and enhancements to existing solutions. As a result, solutions usually take a long time to be delivered and are difficult to modify when business conditions change, as they inevitably do.


Creating Simple Applications Without Programming

Programming creates a major obstacle to developing many custom solutions. Although programming is required for more complex applications, it hinders users who are willing to build simpler systems but lack programming skills.

If users could build their own solutions without writing programs, IS departments would have more time to focus their resources on building organization-wide systems. Users at the departmental and group levels wouldn't have to wait as long to get what they need. At the same time, programmers would benefit from a development environment that can support advanced and highly specialized solutions designed to solve more demanding problems.


Developing Scalable Applications

Microsoft Exchange Server includes a scalable set of tools that enables almost anyone, even users who have never programmed, to develop custom groupware applications. It also enables professional programmers to build advanced business software systems. The following sections describe key Microsoft Exchange Server features that enable end users and programmers to create custom solutions.

Rapid Application Development Without Programming

The Microsoft Exchange Server application design environment enables users to build complete groupware applications, such as customer-tracking systems or electronic discussion forums, without programming. Assuming they have the appropriate permissions, users can copy an existing application (including forms, views, permissions, and rules) and modify it as needed with the functionality available in Microsoft Exchange Client. They can easily modify existing forms or create new ones with Microsoft Exchange Forms Designer, which requires no programming knowledge.

Central Application Management

After users complete an application, they will usually hand it off to an administrator for further testing or distribution to others within the organization. The Microsoft Exchange Server replication engine manages the distribution of the application or any new forms that may have been revised or created for existing applications. You can also replicate these applications from one Microsoft Exchange Server site to another over the Internet by using the Microsoft Exchange Internet Mail Service.

Both of these capabilities translate into reduced cycles for creating, modifying, and distributing groupware applications. This means that end users can build applications that are valuable to them without having to wait for a response from IS. The IS department can further customize these applications, because forms created or modified with Microsoft Exchange Forms Designer are extensible with the Visual Basic programming system. With the Microsoft Exchange Server replication engine, revisions and new applications can be deployed inexpensively as well.

In summary, the rapid application design and delivery process made possible by Microsoft Exchange Server enables those who have the best understanding of the functionality needed for specific applications to respond quickly to their organization's requirements. As a result, an organization can dramatically reduce the costs of adapting and rolling out those applications.


Application Extensibility

As mentioned earlier, Microsoft Exchange Forms Designer permits end users to create forms for public folder and routing applications, without programming. It also enables software developers to customize an application further by generating Visual Basic source code for the form developed. For example, Forms Designer can generate the source code required to send a form through e-mail or to post a form in a folder. To customize forms even further, advanced programmers can use Visual Basic, Professional Edition.

Other workgroup application design tools either require a high degree of programming skill or become outdated whenever an application requires additional functionality. Microsoft Exchange Server bridges the gap between end-user application design and more powerful programming languages.


Sample Applications

The following sample applications included with Microsoft Exchange Server demonstrate the range of customizability that can be supported. The source code for each of these applications is available on the Microsoft Exchange Server 5.0 compact disc.


Chess Sample Application

The Chess sample application shown in the figure below is a custom application written in Visual Basic. This application displays the moves that have been played in a chess game between two Microsoft Exchange Server users.

The right side of the chess board displays the moves made so far. If you click one of the earlier moves, the chess pieces rearrange themselves to the positions they occupied at that point in the game.

This application demonstrates how any application can be created to view information in a Microsoft Exchange Server public folder or browse information in the public folder. And that application can act as the interface through which data is moved in and out of Microsoft Exchange Server, independent of the Microsoft Exchange Client.


Survey Sample Application

The Survey sample application is another example of the level of customization that can be incorporated into Microsoft Exchange Server groupware applications. It is a reusable survey design tool that enables end users to create surveys, either from scratch or by using another survey as a starting point. The sample application was developed with Visual Basic.

The following figure shows a survey in the process of being designed.

The Survey sample application illustrates how you can integrate Microsoft Office and Microsoft Exchange Server applications. For example, a summary of the information collected through the Survey application can be output to Microsoft Word. You can then copy the data into a Microsoft Excel spreadsheet for further analysis or into a Microsoft Word document that can be printed. Because Visual Basic and Microsoft Office applications use the same engine to build custom solutions, you can take advantage of the strengths of each application and programming interface.

If you want to build a customized application closely tied to Microsoft Exchange Server, you can use the Messaging Application Programming Interface (MAPI) Programmer's Reference to integrate your applications with Microsoft Exchange Server or to build a custom gateway. You can tailor the Microsoft Exchange Client interface to meet your specific needs, add functionality to the administrative module, or access virtually any portion of the Microsoft Exchange Server infrastructure.

Microsoft Exchange Server provides a broad and readily defined infrastructure, including support for connectivity to the Internet and X.400 systems, as well as a powerful development kit upon which to build the custom applications you need.


Two Case Studies

The best way to learn about the application design capabilities in Microsoft Exchange Server is to see how organizations can apply them. The following scenarios illustrate how two fictitious companies use these capabilities.


Fabrikam, Inc.: Using the Core Functionality in Microsoft Exchange Server

Fabrikam, Inc. is a multinational company with branch sites throughout the world. It has been running a host-based system as its primary internal e-mail system, although some branches have implemented local area network (LAN)-based e-mail in response to user requests.

A reengineering effort has made it apparent to upper management that to reduce administrative, support, training, and custom-development costs, the company will eventually need to standardize on a single e-mail system. E-mail is considered mission-critical because it is relied on heavily by internal users to transfer information.

In addition, users of the company's LAN-based messaging systems frequently send rich-text objects, such as documents and spreadsheets, and are frustrated with the current messaging environment because it does not enable them to share that information with several branches of the company. And, although users have many good ideas for automating processes by using the messaging infrastructure, the IS department often lacks the ability to create them because of the heterogeneous messaging environments, the difficulty in programming applications on their existing messaging system, and a corresponding lack of resources.

Recommendations

The reengineering effort has produced several key recommendations, including:

  • Take advantage of the messaging infrastructure for groupware applications. The best way to meet cost and functionality objectives is to build groupware applications on a messaging system capable of serving as a mission-critical infrastructure.
  • Use distributed information effectively. The company believes it is important to have an information infrastructure that will enable it to expand on the capabilities of LAN-based messaging systems. This can be accomplished by making the information available where users need it and can interact with it.
  • Empower end users. An organization's messaging system needs to empower end users, making it easy for them to find the information they need and to create the applications that enable them to solve business problems.

After conducting a comprehensive review of a variety of products, Fabrikam, Inc. chose Microsoft Exchange Server as its messaging and workgroup platform. In addition to offering strong messaging, connectivity, and administrative capabilities, Microsoft Exchange Server was selected because it includes built-in groupware and supports building additional groupware applications on top of its messaging system, which can handle the mission-critical demands placed upon it.

Leveraging the Messaging Infrastructure for Groupware Applications

Microsoft Exchange Server provides the functionality required for the following types of groupware applications used by Fabrikam, Inc.:

  • Person-to-person routing applications. Although the company's host-based messaging systems don't support this capability, users of the company's LAN-based system want to use e-mail for routing documents, spreadsheets, and other types of files. This capability, and the frequent need to include other structured information with an attachment (such as forwarding a budget forecast spreadsheet to a vice president, who might then expose information from the spreadsheet as a viewable field in a form), make the creation and routing of point-to-point forms an important capability.
  • Bulletin board applications. A bulletin board can eliminate the usual difficulties associated with storing information in a file system and can automate and provide ready access to that information. Users no longer have to remember a multitude of network paths or passwords to find information. A variety of object types can be stored, including e-mail messages, documents, spreadsheets, slide presentations, and even voice-mail files. The user has a much broader set of options for viewing and finding files that contain OLE custom properties, because the properties can be made visible in the client view.
  • Discussion area (public folder) applications. Discussion areas enable users to participate in discussions in easily identifiable locations, rather than through e-mail, as is currently done at Fabrikam, Inc. It also eliminates the problem of trying to keep track of e-mail threads in end users' Inboxes.
  • Tracking applications. In a workgroup tracking application, users can combine the capabilities of bulletin boards and threaded conversations to create applications that help a group of people collaborate and share information. For instance, a customer-tracking application can enable a sales force to gather the latest information on a potential customer they plan to call on. After the call, the sales force can post information about the call, as well as outstanding customer issues, correspondence, and so on. This capability enables the sales force, who are typically connected only intermittently, to have the latest information. It also enables groups of people who are not necessarily in close physical contact to share information.

Using Distribution Information

Microsoft Exchange Server support for multimaster data replication provides Fabrikam, Inc. the benefits of a distributed information infrastructure. This structure enables users to share ideas and work as a team to reach decisions, even if they are thousands of miles and many time zones apart. Fabrikam, Inc. plans to use this capability to create public folders that contain process discussion plans and enable each functional unit to participate in discussions on the plans, including how they might be improved. In this way, the company will benefit from the involvement of the people who best understand how to reengineer a process.

Another benefit of replicated information is the minimal administrative overhead required to keep multiple versions up-to-date. This overhead has been a problem with the company's current system, because much of the information the company wanted to distribute worldwide first had to be copied manually to local office servers. This meant working with links that may or may not be functioning, that disconnect in the middle of transmissions, and that cause a variety of other administrative problems.

Enabling End Users to Accomplish More

Users at Fabrikam, Inc. can make decisions more easily because they will be able to quickly access the information they need. This functionality is provided by the Microsoft Exchange Client and Microsoft Exchange Server working together. The server moves the information throughout the organization, while the client provides the ability to search through data to find the necessary information. The ability of the Microsoft Exchange Client to group, sort, and filter information creates intelligent agents for handling tasks, support for group scheduling, and the ability for users to develop custom forms and build custom applications without programming. All make it easier for users to communicate.

Fabrikam, Inc. users will also be able to create applications quickly and easily. For example, a user may find a public folder application and want to make a similar application with only a few changes (such as copying the customer-tracking application, including its forms, rules, and permissions). Because the application is provided as a sample application on the Microsoft Exchange Server compact disc, it can be used as a model to create a public folder for tracking contractors and other suppliers, eliminating the need to create a similar application from scratch.

The purpose of each public folder is similar: to provide a centrally accessible location where information on outside organizations can be kept, and to enable users of the folder to enter information as it is gathered. To accomplish these tasks, Fabrikam, Inc. intends to use Microsoft Exchange Forms Designer, and will install Microsoft Exchange Forms Designer on most of the company's desktops running the Microsoft Exchange Client. However, the administrator will retain the sole ability to distribute applications created by users to the rest of the company, typically after the application has been completely tested.

Results

Microsoft Exchange Server provides an e-mail infrastructure that is capable of handling Fabrikam, Inc. employees scattered across the globe, yet can be centrally managed from a single desktop. By providing built-in groupware applications, Microsoft Exchange Server provides users with the ability to work together more efficiently without incurring the additional infrastructure, end-user training, or administrative costs that a separate infrastructure would require. Finally, users can quickly and easily access the information they need and build applications that they feel are most valuable.


Trey Research: Taking Full Advantage of the Microsoft Exchange Server Programmable Interface

Trey Research is a diversified global financial investment company whose organizations provide personal banking, investment counseling and sales, and financial market and economic analysis for internal and external customers. As with Fabrikam, Inc., this company has chosen to standardize its messaging system on Microsoft Exchange Server for a variety of reasons. Key to its decision is the native X.400 and Internet connectivity in Microsoft Exchange Server. This capability is not only an internal standard—it enables the company to share information with its many international customers and information suppliers.

Another key advantage of Microsoft Exchange Server is its ability to build custom applications that integrate the company's desktop application suite with Microsoft Exchange Server. Management at Trey Research plans to take advantage of the built-in customization ability of Microsoft Exchange Server to provide users with quick access to the information they need and the ability to use their desktop tools to analyze and format the information.

These capabilities will be provided through customized applications, which will enable users to use Microsoft Exchange Server public folders as repositories for status reports or downloaded news feeds, and then output that data to Microsoft Office applications for spreadsheet analysis, graphing, and charting. After the data analysis has been completed, the new statistical information will be placed in a Microsoft Exchange Server public folder accessible only to executives for review and comment. By using the replication facility in Microsoft Exchange Server as a distributed information transport, and by using the Microsoft Exchange Internet Mail Service to connect Microsoft Exchange Server sites, Trey Research will ensure that important information is distributed automatically to its offices worldwide.

Trey Research also plans to use Schedule+ for project scheduling by linking data maintained in public folders, Microsoft Project, and Schedule+. Microsoft Exchange Server can also enable the company to take advantage of its investment in Visual Basic training for their corporate developers.

In short, Trey Research plans to take advantage of the same capabilities that Fabrikam, Inc. found useful, and the following additional application design benefits of Microsoft Exchange Server, including:

  • Scalable tools for application design — Many of the solutions Trey Research evaluated as possible workgroup and e-mail infrastructures could only support a limited amount of functionality, or required highly skilled and expensive development resources to implement. Now Trey Research has the tools needed to build applications quickly and to enable their internal development staff to customize applications without worrying about exceeding the functionality available through these tools.
  • Native support for Internet standards — Trey Research can develop applications that gather relevant information from the Internet and distribute it to its other Microsoft Exchange Server sites worldwide, over an Internet backbone.
  • Integration with the Microsoft Office applications suite — Trey Research wants to make the most of its investment in Office by integrating its groupware and e-mail with desktop applications and by adopting a common programmable interface for the two. As a result, users can work with a familiar interface, even with custom applications. In addition, the company's development staff will have a common tool set and programming interface available in Office applications—Visual Basic and the scripting language of Visual Basic for Applications—to integrate desktop applications into workgroup solutions.

Support for Scalable Application Design

If an application created by an end user becomes popular and can be rolled out to the rest of the company, Trey Research wants its more experienced development teams to be able to further customize the application. This means that the company needs a solution that can meet the dual—and often conflicting—goals of enabling users to design applications and forms, and enabling the development staff to make those applications more robust, to integrate them with existing applications, or to add additional functionality. Microsoft Exchange Server was the only workgroup and messaging product evaluated by Trey Research that could provide a scalable application design environment.

After an application is rolled out, users inevitably find ways to improve it, and the competitive environment may require additional customizability. Because forms can be customized with Visual Basic, the desired functionality can be added to Microsoft Exchange Server workgroup solutions that use forms. And, because Visual Basic is a powerful programming language capable of calling any Windows-based API, there is virtually no limit to the functionality that can be added.

Integrating with Desktop Software

Trey Research chose Microsoft Office largely because of the powerful programmability provided by Visual Basic for Applications and the various OLE Automation interfaces available in each Office application. Because Microsoft Exchange Server provides an OLE Automation server for MAPI that can be accessed from Microsoft Office applications and Visual Basic, integrating the company's applications with Microsoft Exchange Server will enable it to take advantage of its existing investment; build applications quickly; and add, customize, or change applications rapidly.

Microsoft Office applications can also be integrated into workgroup solutions offered by Microsoft Exchange Server. Microsoft Office documents and spreadsheets, for example, can be stored in the Microsoft Exchange Server information store, as well as shared between the Office applications and Microsoft Exchange Server.

Trey Research plans to use Microsoft Excel as a reporting mechanism for public folder applications. It will be used by the sales managers to automatically compile periodic contact and sales data. For example, a sales representative can enter information on new customers, outstanding customer issues, and sales closed. A sales manager can use the analysis and charting capabilities of Microsoft Excel to evaluate trends and track the business; and then automate the compiling, publication, and distribution of a report by using Microsoft Word and Microsoft Exchange Server.

Results

By investing in a common technology, Trey Research provides key benefits for its users and developers. Sales managers, for example, are familiar with Microsoft Excel as a data-analysis tool. By integrating Microsoft Exchange Server applications into Microsoft Excel for additional analysis and data manipulation, Trey Research's managers don't have to learn a new tool or interface to conduct their analysis.


Summary

Microsoft Exchange Server provides an application design environment that is ideal for rapidly changing business requirements. It enables all users, from novices to skilled programmers, to create custom applications to improve efficiency and make it easier to communicate. It provides a scalable design environment that makes it easy to modify those applications quickly and cost effectively. It also offers reliable, versatile options for connecting to the Internet and X.400 systems to distribute those applications to users virtually anywhere.

Note The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted.


Chapter 6 MS Exchange Server Registry Reference

This chapter identifies the Registry entries that you can add or change using the Registry Editor. Wherever possible, you should use the Control Panel and the applications in the Windows NT Administrative Tools program group to make changes to the system configuration.


Microsoft Exchange Server Administrator Program Registry Reference

This section provides details on the registry settings used by the Microsoft Exchange Server Administrator program.

Caution You should not change any of the Microsoft Exchange Server registry key values unless you are familiar with the full effect of the change.

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin

Name | Type | Default Value | Description
KMPasswordRemember(flag) |  |  | Tells the Administrator program to remember or forget the password.
KMPasswordRemember(msec) |  |  | Specifies how many milliseconds to remember the password, if the KMPasswordRemember registry key is set to remember.

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin/Desktop

Name | Type | Default Value | Description
AppFrame |  |  | Specifies the Main Frame window size.
Fonts |  |  |
LinkMonitorHeader |  |  | Specifies the header for the link monitor MDI window.
SaveOnExit |  |  |
ShowCmd |  |  | Specifies the startup Administrator window size (minimized or maximized).
StatusBar |  |  |
PermissionsHeader |  |  | Specifies the permissions page columns header.

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin/Desktop/Windowx

Name | Type | Default Value | Description
HListSelection |  |  | The selected item in the Admin tree control
Homeserver |  |  | The server to which this window was connected
MainMapiHeader |  |  | The column header information for the MAPI table on the RHS pane (for example, recipients list)
MainXDSHeader |  |  | The header information for the non-MAPI table on the RHS (for example, List of connectors)
SplitterBarPosn |  |  | The splitter bar that separates the tree control and the VLB
WindowPlacement |  |  | MDI child placement
WindowType |  |  | The type of MDI child (monitor or main explorer window)
MonitorName |  |  | The DN of the monitor that is run in this window (only for monitor MDI child windows)

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin/DefaultBrowseDialogDir

Name | Type | Default Value | Description
ImportFile |  |  |
ExportFile |  |  |
MonitorLog |  |  |
EscalationProcess |  |  |

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin/MostRecentlyUsed/MRUx

Name | Type | Default Value |  | Description
HlistSelection |  |  | The selected item in the Admin tree control
HomeServer |  |  | The server to which this window was connected to
MainMapiHeader |  |  | The column header information for the MAPI table on the RHS pane (such as recipients list)
MainXDSHeader |  |  | The header information for the non-MAPI table on the RHS (such as List of connectors)
SplitterPosition |  |  | Specifies the location of the splitter bar that separates the tree control and the VLB.
WindowPlacement |  |  | MDI child placement
WindowType |  |  | The type of MDI child (monitor or main explorer window)
MonitorName |  |  | The DN of the monitor that is run in this window (only for monitor MDI child windows)

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdmin/FYI

Name | Type | Default Value | Description
NotificationOnNextPass |  |  | Specifies whether or not the Administrator program warns about monitor notifications being delayed until next polling pass or immediately.

Under Registry Key:
H_KEY_CURRENT_USER/SOFTWARE/Microsoft/Exchange/
MSExchangeAdminCommon

Name | Type | Default Value | Description
Options |  |  | Tools Options Setting, common to Administrator and Mailumx Directory structure doc


Microsoft Exchange Server Directory Structure

Setup creates the default directory structure shown here when all components are installed. Note where setup creates shared directories. The directory structure shown here is the default structure if all components are installed with the default values. General Microsoft Exchange Server and Administrator program files are in the \Exchsrvr directory.

Note If you specify a separate directory for the Administrator program, the files that are common to both the Administrator program and Microsoft Exchange Server are duplicated in the \Exchsrvr directory and in the directory you specified for the Administrator program. The files installed in these directories are listed below.


Microsoft Exchange Server Client Files

The files installed depend on the version selected.

  • Windows 95 Client
  • DOS Client
  • Windows NT Client
  • Windows 3.1 or Windows for Workgroups Client


Microsoft Exchange Server Files

  • Setup program
  • Administrator program
  • Microsoft Exchange Server
  • Shared files


Microsoft Windows 95 Client Files

Installed In: CLIENT\WIN95UPG | Installed In: CLIENT\WIN95UPG\SHARED
ACMSETUP.EXE | MSINFO.EXE
ACMSETUP.HLP | MSSP232.DLL
ADMIN.INF | MSSP2_EN.LEX
APNAME.LST |
APPXEC32.DLL |
AV41206.FMT |
AV41256.FMT |
AV41307.FMT |
AV41357.FMT |
BOOMERR.TXT |
BOOMHELP.TXT |
CAN32.CFG |
CARD1.PRT |
CBTLIB4.DLL |
CMC.DLL |
CNFNOT.CFG |
CNFNOT.ICO |
CNFNOT32.EXE |
CNFRES.CFG |
COMDLG16.OCX |
CONFLICT.ICO |
CTL3D3_.DLL |
CTL3DV_.DLL |
CUECARD.HLP |
DATAZAP.DLL |
DATZAP16.DLL |
DATZAP32.DLL |
DAY1.PRT |
DAY2.PRT |
DYNO106.FMT |
EMSABP32.DLL |
EMSUI32.DBG |
EMSUI32.DLL |
EMSUIX32.DBG |
EMSUIX32.DLL |
ETEXCH32.DLL |
EXCHNG.CNT |
EXCHNG.HLP |
EXCHNG.INF |
EXCHGN.LES |
EXCHNG.STF |
EXCHGN32.DBG |
EXCHGN32.EXE |
FORMCOM.HLP |
ILECOMM.DLL |
ILREM.DLL |
ILS.EXM |
ILS.STR |
ILX9600.FIL |
ILXACT.FIL |
ILXECCO.FIL |
ILXHP95.FIL |
ILXLATE.EXE |
ILXLATE.HLP |
ILXMSA.FIL |
ILXORG.FIL |
ILXRAT.FIL |
ILXSHARP.FIL |
ILXSPL2.FIL |
ILXW.DLL |
ILXWPAD.FIL |
MAIL.PRT |
MAPI.DLL |
MAPI32.DBG |
MAPI32.DLL |
MAPIF0.CFG |
MAPIF0L.ICO |
MAPIF0S.ICO |
MAPIF1.CFG |
MAPIF10.CFG |
MAPIF11.CFG |
MAPIF11L.ICO |
MAPIF11S.ICO |
MAPIF1L.ICO |
MAPIF1S.ICO |
MAPIF2.CFG |
MAPIF2L.ICO |
MAPIF2S.ICO |
MAPIF3.CFG |
MAPIF3L.ICO |
MAPIF3S.ICO |
MAPIF4.CFG |
MAPIF4L.ICO |
MAPIF4S.ICO |
MAPIF5.CFG |
MAPIF5L.ICO |
MAPIF5S.ICO |
MAPIF6.CFG |
MAPIF6L.ICO |
MAPIF6S.ICO |
MAPIF7.CFG |
MAPIF7L.ICO |
MAPIF7S.ICO |
MAPIF8.CFG |
MAPIF8L.ICO |
MAPIF8S.ICO |
MAPIF9.CFG |
PAPIFORM.VBX |
MAPIFVBX.REG |
MAPIRPC.REG |
MAPIFSP32.DBG |
MAPISP32.EXE |
MAPISRVR.EXE |
MAPISVC.INF |
MC.ICO |
MCS.ICO |
MDISP.EXE |
MDISP.REG |
MDISP.TLB |
MEFLIB.DLL |
MENUSEL.VBX |
ML3XEC16.EXE |
MLCFG32.CPL |
MLCFG32.DBG |
MLCTRL.DLL |
MLSET32.EXE |
MLSETP32.DBG |
MLSETP32.DLL |
MMFMIG32.DLL |
MONTH1.PRT |
MR.ICO |
MRN.ICO |
MRP.ICO |
MRPS.ICO |
MRS.ICO |
MRT.ICO |
MRTS.ICO |
MSCAL32.DLL |
MSCALL16.OCX |
MSCPYDIS.DLL |
MSFS.CNT |
MSFS.HLP |
SMFS32.DBG |
MSFS32.DLL |
MSPST32.DBG |
MSPST32.DLL |
MSRICHED.VBX |
MSSCD32.DLL |
MSSETUP.DLL |
MSSPC32.DLL |
MSTABCTL.VBX |
MSTRE32.DLL |
MSTRS32.DLL |
MSVCRT20.DLL |
NORMAL.FMT |
OC25.DLL |
PLAY.EXE |
README.TXT |
ERGOCX16.EXE |
REQ32.CFG |
RICHED.DLL |
RICHED32.DBG |
RICHED32.DLL |
RPN32.CFG |
RPP32.CFG |
RPT32.CFG |
SCANPST.HLP |
SCHDPL32.EXE |
SCHDPLUS.CNT |
SCHDPLUS.HLP |
SCHDPLUS.LES |
SECURE.CFG |
SECURL.ICO |
SECURS.ICO |
SETUP.EXE |
SETUP.INI |
SETUP.LST |
SIGN.CFG |
SIGNLRG.ICO |
SIGNSM.ICO |
SPIN16.OCX |
SPUS_BB.DLL |
TABLES.ITB |
TASK1.PRT |
TASK2.PRT |
TASK3.PRT |
TEXT1.PRT |
THREED16.OCX |
TRIFOLD3.PRT |
VAEN2.DLL |
VAEN2.OLB |
VB40016.DLL |
VB4EN16.DLL |
VB4STP32.DLL |
VLB.DLL |
VLB32.DLL |
WEEK1.RPT |
WEEK2.RPT |
WMSFR.DLL |
WMSFR32.DBG |
WMSFR32.DLL |
WMSUI.DLL |
WMSUI32.DBG |
WMSUI32.DLL |


DOS Client Files

Installed In: CLIENT\DOS | Installed In: CLIENT\NTX86\SHARED
_MSSETUP.EXE |
CONNECT.EXE | MSINFO.EXE
CONNECT.HLP | MSSP232.DLL
DIALNDIS.EXE | MSSP2_EN.LEX
DIALODI.EXE |
EXCHANGE.EXE |
EXDCHANGE.HLP |
MLSETUP.INI |
MODEMS.INI |
README.TXT |
RPC16C1.RPC |
RPC16C3.RPC |
RPC16C4.RPC |
RPC16C5.RPC |
RPC16C6.RPC |
RPC16DG3.RPC |
RPC16DG6.RPC |
PRCNS.RPC |
RPCNSLM.RPC |
RPCNSMGM.RPC |
SECURITY.RPC |
SETUP.EXE |
SETUP.INF |


Windows NT Client Files

Installed In: CLIENT\NTX86

ACMSETUP.EXE

ACMSETUP.HLP

ADMIN.INF

APNAME.LST

APPXEC32.DLL

AV41206.FMT

AV41256.FMT

AV41307.FMT

AV41357.FMT

BOOMERR.TXT

BOOMHELP.TXT

CAN32.CFG

CARD1.PRT

CBTLIB4.DLL

CMC.DLL

CNFNOT.CFG

CNFNOT32.EXE

CNFRES.CFG

COMDLG16.OCX

CONFICT.ICO

CTL3D3_.DLL

CTL3DV_.DLL

CUECARD.HLP

DATAZAP.DLL

DATZAP16.DLL

DATZAP32.DLL

DAY1.PRT

DAY2.PRT

DYNO106.FMT

EMSABP32.DLL

EMSMDB32.DLL

EMSUI32.DBG

EMSUI32.DLL

EMSUIX32.DLL

ETEXCH32.DLL

EXCFG32.EXE

EXCHNG.CNT

EXCHNG.HLP

EXCHNG.INF

EXCHNG.LES

EXCHNG.STF

EXCHNG32.DBG

EXCHNG32.EXE

FAXVIEW.EXE

FORMCOM.HLP

ILECOMM.DLL

ILREM.DLL

ILS.EXM

ILS.STR

ILX9600.FIL

ILXACT.FIL

ILXECCO.FIL

ILXORG.FIL

ILXRAT.FIL

ILXSHARP.FIL

ILXSPL2.FIL

ILXW.DLL

ILXWPAD.FIL

MAIL.PRT

MAPI.DLL

MAPI32.DBG

MAPI32.DLL

MAPIF0.CFG

MAPIF0L.ICO

MAPIF0S.ICO

MAPIF1.CFG

MAPIF10.CFG

MAPIF11.CFG

MAPIF11L.ICO

MAPIF11S.ICO

MAPIF1L.ICO

MAPIF1S.ICO

MAPIF2.CFG

MAPIF2L.ICO

MAPIF2S.ICO

MAPIF3.CFG

MAPIF3L.ICO

MAPIF3S.ICO

MAPIF4.CFG

MAPIF4L.ICO

MAPIF4S.ICO

MAPIF5.CFG

MAPIF5L.ICO

MAPIF5S.ICO

MAPIF6.CFG

MAPIF6L.ICO

MAPIF6S.ICO

MAPIF7.CFG

MAPIF7L.ICO

MAPIF7S.ICO

MAPIF8.CFG

MAPIF8L.ICO

MAPIF8S.ICO

MAPIF9.CFG

MAPIFORM.VBX

MAPIFVBX.REG

MAPIFVBX.TLB

MAPIRPC.REG

MAPISP32.DBG

MAPISP32.EXE

MAPISRVR.EXE

MAPISVC.INF

MC.ICO

MCS.ICO

MDISP.EXE

MDISP.REG

MDISP.TLB

MEFLIB.DLL

MENUSEL.VBX

MHCOMD.VBX

ML3XEC16.EXE

MLCFG32.CPL

MLCFG32.DBG

MLCTRL.DLL

MLSETP32.DBG

MLSETP32.DLL

MMFMIG32.DLL

MONTH1.PRT

MR.ICO

MRN.ICO

MRNS.ICO

MRP.ICO

MRPS.ICO

MRS.ICO

MRT.ICO

MRTS.ICO

MSCAL32.DLL

MSCALL16.OCX

MSCPYDIS.DLL

MSFS.HLP

MSFS32.DBG

MSPST32.DLL

MSRICHED.VBX

MSSCD32.DLL

MSSETUP.DLL

MSTABCTL.VBX

MSTRE32.DLL

MSTRS32.DLL

MSVCRT20.DLL

NORMAL.FMT

OC25.DLL

PLAY.EXE

README.TXT

REGOCX16.EXE

REQ32.CFG

RICHED.DLL

RICHED32.DBG

RICHED32.DLL

RPN32.CFG

RPP32.CFG

RPT32.CFG

SCHDPL32.EXE

SCHDPLUS.HLP

SCHDPLUS.LES

SECURE.CFG

SECURL.ICO

SECURS.ICO

SETUP.EXE

SETUP.INI

SETUP.LST

SIGN.CFG

SIGNLRG.ICO

SIGNSM.ICO

SPIN16.OCX

SPLUS_BB.DLL

TABLES.ITB

TASK1.PRT

TASK2.PRT

TASK3.PRT

TEXT1.PRT

THREED16.OCX

TRIFOLD3.PRT

VAEN2.DLL

VAEN2.OLB

VB40016.DLL

VB4EN16.DLL

VB4STP32.DLL

VLB.DLL

VLB32.DBG

VLB32.DLL

WEEK1.RPT

WEEK2.RPT

WMSFR.DLL

WMSUI.DLL

WMSUI32.DBG

WMSUI32.DLL

_MSSETUP.EXE


Windows 3.1 or Windows for Workgroups Client Files

Installed In: CLIENT\WIN16

ACMSETUP.EXE

ACMSETUP.HLP

ADMIN.INF

APNAME.LST

APPXEC32.DLL

AV41206.FMT

AV41256.FMT

AV41307.FMT

AV41357.FMT

BOOMERR.TXT

BOOMHELP.TXT

CALLIN.BAT

CAN16.CFG

CARD1.PRT

CBTLIB4.DLL

CMC.DLL

CNFNOT.CFG

CNFNOT.EXE

CNFRES.CFG

COMDLG16.OCX

COMPDRV.EXE

COMPOBJ.DLL

CONFIG.HLP

CONFIG.TXT

CONFLICT.ICO

CONNAPI.DLL

CONNECT.EX_

CONNECT.HLP

CONNECTW.EX_

CONNECTW.HLP

CTL3D.DLL

CTL3DV.DLL

CUECARD.HLP

DATAZAP.DLL

DAY1.PRT

DAY2.PRT

DEMILAYR.DLL

DIAL.386

DIALCOMP.EXE

DIALNDIS.EXE

DIALODI.EXE

DISPDIB.DLL

DWSPYDLL.DLL

DYNO106.FMT

EMSABP.DLL

EMSMDB.DLL

EMSUI.DLL

EMSUIX.DLL

ETEXCH.DLL

EXCFG.EXE

EXCHNG.EXE

EXCHNG.HLP

EXCHNG.INF

EXCHNG.LES

EXCHNG.STF

FAXVIEW.EXE

FORMCOM.HLP

GUARD.EXE

HANGUP.BAT

ILECOMM.DLL

ILREM.DLL

ILS.EXM

ILS.STR

ILX9600.FIL

ILXACT.FIL

ILXECCO.FIL

ILXHP95.FIL

ILXLATE.EXE

ILXLATE.HLP

ILXMSA.FIL

ILXORG.FIL

ILXRAT.FIL

ILXSHARP.FIL

ILXSPL2.FIL

ILXW.DLL

ILXWPAD.FIL

MAIL.PRT

MAILMGR.DLL

MAPI.DLL

MAPIF0.CFG

MAPIF0L.ICO

MAPIF0S.ICO

MAPIF1.CFG

MAPIF10.CFG

MAPIF11.CFG

MAPIF11L.ICO

MAPIF11S.ICO

MAPIF1L.ICO

MAPIF1S.ICO

MAPIF2.CFG

MAPIF2L.ICO

MAPIF2S.ICO

MAPIF3.CFG

MAPIF3L.ICO

MAPIF3S.ICO

MAPIF4.CFG

MAPIF4L.ICO

MAPIF4S.ICO

MAPIF5.CFG

MAPIF5L.ICO

MAPIF5S.ICO

MAPIF6.CFG

MAPIF6L.ICO

MAPIF6S.ICO

MAPIF7.CFG

MAPIF7L.ICO

MAPIF7S.ICO

MAPIF8.CFG

MAPIF8L.ICO

MAPIF8S.ICO

MAPIF9.CFG

PAPIFORM.VBX

MAPIFVBX.REG

MAPIRPC.REG

MAPISP.EXE

MAPISVC.INF

MC.ICO

MCS.ICO

MDISP.EXE

MDISP.REG

MDISP.TLB

MEFLIB.DLL

MENUSEL.VBX

MLCFG.DLL

MLCTRL.DLL


Microsoft Exchange Server Information Store Registry Key Structure

The following diagram shows the keys created in the registry when information store is installed by Microsoft Exchange Server Setup.


Microsoft Exchange Server Information Store Registry Reference

This section provides the details on the registry settings used by the Information Store. Values that are shown bold are created by Server Setup. Values that are not bold are not visible until you create them. If you do not specify a value, the default value is used. If you specify a value that is outside the minimum or maximum value, the maximum or minimum is used, respectively.

  • Key Structure
  • Key/Value Hierarchy

Caution You should not change any of the Microsoft Exchange Server registry key values unless you are familiar with the full effect of the change.

Under Registry Key:
SYSTEM\CURRENTCONTROLSET\SERVICES\MSEXCHANGEIS\
PARAMETERSSYSTEM

Name | Type |  | Default Value |  | Description
Aging Clean Interval |  |  | 900 |  | Units: Seconds Min: 60 Max: 3600 Column Aging and Index Aging occurs during the Maintenance Schedule set in Administrator on the server object. This interval indicates how long to wait after the start of a clean before starting another clean. If the clean takes longer than this interval, a new clean is started immediately after the first clean completes.
Aging Keep Time |  |  | 900 |  | Units: Seconds Min: 60 Max: 3600 Column Aging and Index Aging occurs during the Maintenance Schedule set in Administrator on the server object. This interval indicates how long to keep columns of indices before they are cleaned.
Circular Logging |  |  |  |  | Whether to use Jet circular logging. This causes transaction log files to be reused. When this is on, differential and incremental backups will not work. The information store service must be restarted to reread this value after it is toggled.
DB Log Path |  |  |  |  | Where Edb*.log files go
DB Recovery |  |  |  |  | Whether to activate logging/recovery. 0 = no, 1 = yes.
DB System Path |  |  |  | Path where System.edb is located.
DS Computer |  |  |  | Server where the DS to use is located
Max Threads |  |  |  | Maximum number of threads that are created by the information store service.
MTA Computer |  |  |  | Server where the MTA to use is located
Online Compaction |  |  |  | On or off
Reread GWART Interval |  | 900 |  | Units: Seconds Min: 60 Max: 3600 The interval at which the GWART is reread so that new gateways can be detected.
Reread Information Store Quotas Interval |  | 900 |  | Units: Seconds Min: 60 Max: 3600 The interval at which quotas on the information store object in the DS are read in order to update.
Synch Mailbox/Check OOF Interval |  | 900 |  | Units: Seconds Min: 60 Max: 3600
This Server |  |  |  | Name of this server
Working Directory |  |  |  | Path to working directory for information store

Under Registry Key:
System\CurrentControlSet\Services\MSExchangeIS\ParametersPrivate

Name | Type | Default Value | Description
Clean Per User Read Interval |  | 900 | Units: Seconds Min: 60 Max: 3600 Cleaning per user read occurs during the Maintenance Schedule set in Administrator on the server object. This interval indicates how long to wait after the start of a clean before starting another clean. If the clean takes longer than this interval, a new clean is started immediately after the first clean completes.
DB Path |  |  | Path where Expriv.eis is located.
Disabled |  |  | Disables the Private store. 0 = Not disabled. 1 = Disabled.
General Event Log |  |  | Mask used to control which sub-categories within each event log category are actually written to the NT event log. Its default value is 0. This will cause a few very basic (start and stop) events to be logged. Set mask to 0xFFFFFFFF to log all events.
Log Downloads |  |  | Bit mask to control which download actions (items copied out of the information store) are written to the event log. Normally set to 0 (default) for the Private information store. Bits: 0x1 Attachment downloads 0x2 Message downloads 0x4 Folder downloads
Reread Logon Quotas Interval |  | 900 | Units: Seconds Min: 60 Max: 3600 This interval indicates how often to read logon object quotas from the DS.
Track Duplicates |  | 1 | Units: Hours Min: 1 Max: 24 Time interval for which duplicates are tracked at delivery. This is the interval for which information on received messages will be kept and duplicates will be eliminated. The BackgroundCleanup task must be enabled for this to work.
Transport Event Log |  |  | See Private General Event Log

Under Registry Key:
System\CurrentControlSet\Services\MSExchangeIS\ParametersPublic

Name | Type |  | Default Value |  | Description
DB Path |  |  |  |  | Path where Expub.eis is located.
Disabled |  |  |  |  | Disables the Public store. 0 = Not disabled. 1 = Disabled.
General Event Log |  |  |  |  | Mask used to control which sub-categories within each event log category are actually written to the NT event log. This will cause a few very basic (start and stop) events to be logged. Set mask to 0xFFFFFFFF to log all events.
Log Downloads |  |  |  |  | Bit mask to control which download actions (items copied out of the information store) are written to the event log. Bits: 0x1 Attachment downloads 0x2 Message downloads 0x4 Folder downloads
Maximum Cached Categorizations |  |  |  |  |
Read PF Instances Interval |  |  | 900 |  | Units: Seconds Min: 60 Max: 3600 This interval indicates how often to read the DS to determine which public folders are replicated to this server.
Read PF Settings Interval |  |  | 900 |  | Units: Seconds Min: 60 Max: 3600 This interval indicates how often to read the DS to determine the replication configuration of public folders that are replicated to this server.
 |  |  |  |  | Replication has 3 possible values (the default value is 1): 0: replication disabled 1: replication enabled, with default settings (registry overrides are ignored) 2: replication enabled, using registry overrides, if they are available.
 |  |  |  |  | Replication Backfill Timeout (Solicited): Timeout value used for testing backfill. Don't change the default value.
 |  |  |  | Replication Backfill Timeout (Unsolicited): Timeout value used for testing backfill. Don't change the default value.
 |  | 900 |  | Replication DS Updates Units: Seconds Min: 900 Max: 3600 This is the time interval at which the replication agent will look for updates from the directory service. This requires a DS call for every folder in the IPM subfolder tree, and the DS calls are very slow right now (up to 20 seconds per call), so don't set this value too small.
Replication Event Log |  |  |  | This is a 32-bit mask of the replication sub-categories used when writing to the Windows NT event log (application). Enabling the appropriate bits listed below will enable detailed information about various specific areas of replication. It is intended primarily for debug use, but will ship as part of the product, to help track down problems in the field. // equivalent to TraceError - will list every function and its error code returned #define elscLogError (ELSC)0x80000000 // report high level replication errors #define elscReplError (ELSC)0x00000001 // report changes from the directory service #define elscReplDs (ELSC)0x00000002 // report information related to incoming replication messages #define elscReplMsgIn (ELSC)0x00000004 // report information on outgoing replication messages #define elscReplMsgOut (ELSC)0x00000008
Replication Event Log (cont.) |  |  |  | // report information on the MDBs to which a replication message is mailed #define elscReplMsgOutRecipients (ELSC)0x00000010 // report information on replication conflicts, and their resolution #define elscReplConflict (ELSC)0x00000020 // report information on replication message timeouts #define elscReplTimeout (ELSC)0x00000040 // report information on message expiration by age limit from public folders #define elscReplExpiry (ELSC)0x00000080 This default setting is 0, which will cause only the replication agent start and stop to be written to the Windows NT event log. The other subcategories are subject to change without notice, as is the format of the entries in the event log. Additional subcategories will be added in the future. If you want to see all of the possible replication category event log entries, set the "Replication Event Log" value to 0xFFFFFFFF. You need a lot of disk space for this.
Replication Expiry |  | 900 |  | Units: Seconds Min: 60 Max: 3600 Messages are expired during the Maintenance Schedule set in Administrator on the server object. This interval indicates how long to wait after the start of the last expiry before starting another expiry. If the expiry takes longer than this interval, a new expiry is started immediately after the first expiry completes.
Replication Folder Count Limit |  | 10 |  | Because public folders are slow to create, transport replication message size limits and internal size limits, it is necessary to place a folder count limit (per replication message). If 20 folders have been created but not yet replicated, and the "Replication Folder Count Limit" is set to 10, then the first 10 folders will be sent in 1 replication message, immediately followed by the next 10 in another replication message.
Replication Message Count Limit |  | 20 |  | Same as Replication Folder Count Limit, but for messages.
Replication RMR Timeout |  | 3600 |  | Units: Seconds Min: 60 Max: 3600 This is the time interval that replication messages which cannot be processed will be held.
Replication Send Folder Tree |  | 60 |  | Units: Seconds Min: 60 Max: 3600 Used to override the default rate at which the folder hierarchy is replicated.
Replication Status Updates |  | 3600 |  | Units: Seconds Min: 60 Max: 3600 Time interval at which status broadcasts will be sent for a folder. When this much time has passed with no replication messages sent for a given folder, a status message will automatically be sent.
Replication Timeout |  | 60 |  | Units: Seconds Min: 60 Max: 900 This is the frequency at which the replication agent will check its internal state tables for backfill timeouts. Smaller values will cause timeouts to be detected closer to the actual timeout, but also tend to swamp the server. Don't change the default value unless you know what you are doing.
Track Duplicates |  | 1 |  | Units: Hours Min: 1 Max: 24 Time interval for which duplicates are tracked at delivery. This is the number of hours for which information on received messages will be kept and duplicates will be eliminated. The BackgroundCleanup task must be enabled for this to work.
Transport Event Log |  |  |  | See Public General Event Log.

Under Registry Key:
System\CurrentControlSet\Services\EventLog\Application\MSExchangeIS

Name | Type | Default Value | Description
CategoryCount |  |  | Specifies the number of categories supported.
CategoryMessageFile |  |  | Specifies the path and filename for the category message file.
EventMessageFile |  |  | Specifies the path and filename for the event identifier message file.

Under Registry Key:
System\CurrentControlSet\Services\EventLog\Application\
MSExchangeIS Private

Name | Type | Default Value | Description
CategoryCount |  |  | Specifies the number of categories supported.
CategoryMessageFile |  |  | Specifies the path and filename for the category message file.
EventMessageFile |  |  | Specifies the path and filename for the event identifier message file.

Under Registry Key:
System\CurrentControlSet\Services\EventLog\Application\MSExchangeIS Public

Name | Type | Default Value | Description
CategoryCount |  |  | Specifies the number of categories supported.
CategoryMessageFile |  |  | Specifies the path and filename for the category message file.
EventMessageFile |  |  | Specifies the path and filename for the event identifier message file.

Under Registry Key:
System\CurrentControlSet\Services\MSExchangeIS

Name | Type | Default Value | Description
DependOnGroup |  |  | The Group this service belongs to. For the information store, none.
DependOnService |  |  | Services the information store depends on. For the information store, MSExchangeDS.
DisplayName |  |  | Long display name of the service. For the information store, Microsoft Exchange Information Store.
ErrorControl |  |  | Specifies the severity of the error if the information store fails to start during startup and determines the action taken by the startup program if failure occurs.
ImagePath |  |  |  | Path to .Exe file for information store service.
ObjectName |  |  |  | Specifies the machine account for the context that the service will be run under.
Start |  |  |  | Specifies when to start the service (autostart, manual start, disabled, etc.)
Type |  |  |  | Specifies the type of service (Win32 process, Windows NT device driver, Windows NT file system driver, etc.)

Under Registry Key:
System\CurrentControlSet\Services\MSExchangeIS\Performance

These are all Performance Monitor settings.

Name | Type | Default Value | Description
Close |  |  |
Collect |  |  |
First Counter |  |  |
First Help |  |  |
Last Counter |  |  |
Last Help |  |  |
Library |  |  |
Open |  |  |

Under Registry Key:
System\CurrentControlSet\Services\MSExchangeIS\Security

Name | Type | Default Value | Description
Security |  |  |


Microsoft Exchange Server Tools and Reference

This section provides access to the following Microsoft Exchange Server online information:

  • Windows NT Registry Settings Reference
  • File Reference and Directory Structure


Windows NT Registry Settings Reference

This section covers only the Windows NT Registry entries that are added or modified by Microsoft Exchange Server.

Caution Most of the Microsoft Exchange Server registry key values should not be changed by editing the registry. Use this section for information only. If manual editing is supported, the registry entry is bolded and "Can Edit" is noted in the file.

Example:

If you have this registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIMC
\Parameters\<parameter>

You would specify the BadInMessageAction parameter for this registry key as follows, on one line:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\MSExchangeIMC
\Parameters\BadInMessageAction = 1

For information on finding and editing keys in the registry or using the Registry Editor, see the Windows NT Resource Guide.


File Reference and Directory Structure

This section describes the files and directory structure that Microsoft Exchange Server installs during setup.

  • Directory Structure
  • File Reference


Microsoft Exchange Server MTA Registry Reference

This section describes how configuration information from the Windows NT Registry is used by the Microsoft Exchange Server message transfer agent (MTA).

This section includes those registry parameters that are created by Microsoft Exchange Server Setup and those that can be manually added later for specific functionality. The registry items that are optional and not created by setup are denoted by an asterisk (*) following the name. Registry values with asterisks will not always be found within the MTA Parameters section of the registry. The Registry keys and defaults are all defined in the file Ntil\cc\mtareg.h.

Caution You should not change any of the Microsoft Exchange Server registry key values unless you are familiar with the full effect of the change.

Under Registry Key:

#Define for KEY | Registry Key Name | Default
SCT_CALL_STACK | "Call-stack diagnostics required" | 1
SCT_NCC_TP0_TEST | "NCC TP0 Conformance Tester" | 0
SCT_MDB_USERS | "MDB users" | 1500
SCT_MMI_CONNS | "MMI connections" | 8
SCT_MDB_DEL_Q | "Concurrent MDB/delivery queue clients" | 50
SCT_MT_GWY_CLI | "MT gateway clients" | 10
SCT_RET_Q_CLI | "Retrieval queue clients" | 10
SCT_LMTA_CONNS | "Concurrent connections to LAN-MTAs" | 40
SCT_RAS_CONNS | "Concurrent connections to RAS LAN-MTAs" | 10
SCT_CONC_LMTAS | "Number of LAN-MTA entities" | 20
SCT_X400_GWYS | "Number of X.400 gateway entities" | 20
SCT_CLIENT_TCBS | "XAPI/MMI client DMOD threads" | 10
SCT_MTA_TCBS | "LAN-MTA DMOD threads" | 5
SCT_RAS_TCBS | "RAS LAN-MTA DMOD threads" | 2
SCT_TP4_CBS | "TP4 control blocks" | 20
SCT_TP4_THDS | "TP4 threads" | 2
SCT_TP4_SELECT | "TP4 Async notify timeout (msec)" | 100
SCT_RFC_CBS | "TCP/IP control blocks" | 20
SCT_RFC_THDS | "TCP/IP threads" | 2
SCT_RFC_SELECT | "TCP/IP Async notify timeout (msec)" | 100
SCT_XAPI_APPL | "XAPI MA threads" | 1
SCT_XAPI_GWAY | "XAPI MT threads" | 1
SCT_XAPI_DEL | "XAPI MA queue threads" | 1
SCT_XAPI_XFER | "XAPI MT queue threads" |
SCT_XAPI_SESS | "Concurrent XAPI sessions" | 100
SCT_MTA_SUB | "Submit/deliver threads" | 1
SCT_MTA_DSP | "Dispatcher threads" | 1
SCT_MTA_XFER | "Transfer threads" | 1
SCT_DS_CACHE | "ds_read cache latency (secs)" | 60
SCT_DS_SEARCH | "ds_search latency (mins) for transport stacks" | 60
SCT_PLAT_RTS | "RTS threads" | 1
SCT_PLAT_KER | "Kernel threads" | 1
SCT_OSI_DBUFS | "DB data buffers per object" | 5
SCT_OSI_DBFILE | "DB file handles" | 64
SCT_X400_SVC_LOG | "X.400 Service Event Log" | 0
SCT_EICON_WAIT | "Eicon wait timeout (msec)" | 500
SCT_EICON_RESULT | "Eicon X.25 result threads" | 2
SCT_EICON_CONNS | "Eicon X.25 connections" | 32
SCT_DB_FILECOUNT | "DB file count delete threshold" | 0
SCT_DB_FILESIZE | "DB file size delete threshold" | 0
SCT_RAMREC_SEV0 | "RAM log severity (X.400 Service)" | 4
SCT_RAMREC_SEV1 | "RAM log severity (Resource)" | 4
SCT_RAMREC_SEV2 | "RAM log severity (Security)" | 4
SCT_RAMREC_SEV3 | "RAM log severity (Interface)" | 4
SCT_RAMREC_SEV4 | "RAM log severity (Field Engineering)" | 4
SCT_RAMREC_SEV5 | "RAM log severity (Operator event)" | 4
SCT_RAMREC_SEV6 | "RAM log severity (Configuration)" | 4
SCT_RAMREC_SEV7 | "RAM log severity (Directory Access)" | 4
SCT_RAMREC_SEV8 | "RAM log severity (Operating System)" | 4
SCT_RAMREC_SEV9 | "RAM log severity (Internal Processing)" | 4
SCT_LOG_APDUS | "APDU logging required" | 0
MTA_DIRNAME_KEY | "X500 DN" | Constructed from setup parameters
DSA_ADDRESS_KEY | "DSA Address" | Constructed from setup parameters
MTA_RUNDIR_KEY | "MTA Run Directory" | Constructed from setup parameters
SCT_SECURE_RSLT | "Flush Results to Disk" | 1
SCT_RAS_MTAS | "Number of RAS LAN-MTAs" | 10
SCT_LAN_SITES | "Number of remote sites connected over LAN" | 25
SCT_MAX_DLS | "Number of DLs allowed" | 100
SCT_MAX_XAPI_APPS | "Max concurrent XAPI applications" | 10
SCT_MAX_RPC_CALLS | "Max RPC calls outstanding" | 50
SCT_MIN_RPC_THREAD | "Min RPC Threads" | 4
SCT_RPC_AUTH_LEVEL | "RPC Authentication Level" | 2
SCT_REDISPATCH | "Dispatch remote MTA messages" | 0
SCT_TEXT_LOG | "Text Event Log" | 0
SCT_ENABLE_SEH | "Handle Exceptions" | 0
SCT_DB_FILE_PATH | "MTA database path" | Constructed from setup parameters


Registry Key Descriptions

Call-stack diagnostics required

Provides a call stack for each MTA thread at termination time. This option is a performance hit and is only available on the debug MTA.

NCC TP0 Conformance Tester

Binds the MTA TP0 code to the NCC conformance test tool rather than the MTA upper layers, for conformance testing.

MDB users

Maximum number of MDB users supported by the MTA. Users in Microsoft Exchange are MDB users by default unless explicitly set otherwise.

MMI connections

Maximum number of MMI connections to the MTA. Each Administrator instance using the MTA Administrator API uses one MMI connection and is treated as an MMI client.

Concurrent MDB/Delivery Queue clients

Maximum number of MDBs and XAPI MA Delivery Queue clients supported by the MTA. This should be set to at least two to support the Private and Public MDB entities.

MT Gateway clients

Maximum number of XAPI MT Gateway clients supported by the MTA.

Retrieval Queue clients

Maximum number of XAPI MA Retrieval Queue clients supported by the MTA.

Concurrent connections to LAN-MTAs

Maximum number of concurrent connections to MTAs over the LAN. MTAs communicating over the LAN are known as LAN-MTAs.

The local MTA may have multiple connections to a remote MTA depending on configuration and system load.

Concurrent connections to RAS LAN-MTAs

Maximum number of concurrent connections to remote MTAs over RAS.

Number of LAN-MTA entities

Maximum number of LAN-MTAs supported by the MTA.

Number of X.400 gateway entities

Maximum number of remote MTAs connecting via X.400 OSI links (as opposed to connecting over LAN-MTA or RAS). OSI links use X.25, RFC1006(TCP/IP) or TP4.

XAPI/MMI client DMOD threads

Maximum number of MTA DMOD threads to handle connections to:

  • MDB/XAPI MA Delivery Queue clients
  • XAPI MA Retrieval Queue clients
  • XAPI MT Gateway clients
  • MMI clients

All MTA DMOD threads (of whatever type) can support multiple connections. Connections are load-shared over threads of the same type.

LAN-MTA DMOD threads

Maximum number of MTA DMOD threads to handle connections to LAN-MTAs.

RAS LAN-MTA DMOD threads

Maximum number of MTA DMOD threads to handle RAS connections to remote MTAs.

TP4 control blocks

Maximum number of concurrent TP4 connections supported.

TP4 threads

Maximum number of MTA DMOD threads handling TP4 connections. This is multiplied by two for the two subtypes (Driver, Async Notify) of TP4 threads.

TP4 async notify timeout (msec)

Timeout on select() call for asynchronous notification. This value is the maximum time before the first send/receive on a new connection will be noticed after the connection is established.

TCP/IP control blocks

Maximum number of concurrent RFC1006(TCP/IP) connections supported.

TCP/IP threads

Maximum number of MTA DMOD threads handling RFC1006 connections. This number is multiplied by two for the two subtypes (Driver, Async Notify) of RFC1006 thread.

TCP/IP async notify timeout (msec)

Timeout on select() call for asynchronous notification. This value is the maximum time before the first Send/Receive on a new connection will be noticed after the connection is established.

Eicon wait timeout (msec)

Timeout on x25done() call for asynchronous notification. This value is the maximum time before the first Send/Receive on a new connection will be noticed after the connection is established.

Eicon X.25 result threads

Number of MTA DMOD threads handling EICON X.25 connections.

Eicon X.25 connections

Maximum number of concurrent EICON X.25 connections supported.

XAPI MA threads

Number of threads handling calls from:

  • MDB/XAPI MA Delivery Queue clients
  • XAPI MA Retrieval Queue clients

XAPI MT threads

Number of threads handling calls from:

  • XAPI MT Gateway clients

XAPI MA queue threads

Number of threads handling interaction with the MTA on behalf of:

  • MDB/XAPI MA Delivery Queue clients
  • XAPI MA Retrieval Queue clients

XAPI MT queue threads

Number of threads handling interaction with the MTA on behalf of:

  • XAPI MT Gateway clients

Concurrent XAPI sessions

Maximum number of concurrent connections to:

  • MDB/XAPI MA Delivery Queue clients
  • XAPI MA Retrieval Queue clients
  • XAPI MT Gateway clients

Submit/Deliver threads

Number of MTA Submit/Deliver threads

Dispatcher threads

Number of MTA Dispatcher threads. This is multiplied by three for the three subtypes (Router, Fanout, Result) of Dispatcher thread.

Transfer threads

Number of MTA Transfer threads. This is multiplied by two for the two subtypes (Transfer In, Transfer Out) of Transfer thread.

ds_read cache latency (secs)

Information read from the directory is saved in the ds_read cache. This field determines the cache latency. A higher latency means directory information is read less often, but directory changes may not be noticed until the cache latency time expires.

ds_search latency (mins) for transport stacks

Time interval between directory searches for transport stacks. New transport stacks added to the directory may not be processed until this time interval expires.

RTS threads

Number of platform threads handling the RTSE level of the OSI stack.

Kernel threads

Number of platform threads handling the Presentation and Session level of the OSI stack.

DB data buffers per object

Number of DB Server buffers configured per DB object. More buffers require more memory but make it less likely for a DB object to be rolled out to disk due to lack of buffer space.

DB file handles

Number of DB Server file handles configured. This determines the maximum number of DB files open concurrently. If more Opens are required than the configured value, DB objects will be rolled out to disk.

DB file count delete threshold

DB Server files with a file count greater than this will be deleted once they are finished with. Old unused files are reused, therefore a higher value improves performance by reducing the number of File Delete and Create calls

DB file size delete threshold

DB Server files bigger than this size are be deleted once they are finished with. A higher value improves performance by reducing the number of File Delete and Create calls.

RAM log severity (X.400 Service)

MTA X.400 Service events with a severity equal to or higher than this are logged to the RAM/Termination log. The MTA RAM log is dumped out at termination time.

RAM log severity (Resource)

MTA Resource events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Security)

MTA Security events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Interface)

MTA Interface events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Field Engineering)

MTA Field Engineering events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Operator event)

MTA Operator events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Configuration)

MTA Configuration events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Directory Access)

MTA Directory Access events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Operating System)

MTA Operating System events with a severity equal to or higher than this are logged to the RAM log.

RAM log severity (Internal Processing)

MTA Internal Processing events with a severity equal to or higher than this are logged to the RAM log.

APDU logging required

When set this option logs all APDUs sent or received by the MTA to file.

Flush Results to Disk

Secure message transfer results to avoid duplicate messages being sent after outages. Performance will be improved if results are not secured, but there is a good chance that there will be duplicate messages received by recipients if the MTA terminates unexpectedly .

Number of RAS LAN-MTAs

Maximum number of RAS LAN-MTAs supported by the MTA.

Number of remote sites connected over LAN

Maximum number of remote sites connected over the LAN. This equates to the number of Virtual Domains/Site Connectors in this site.

Number of DLs allowed

Maximum number of DLs supported by the MTA.

X500 DN

Full directory name of the MTA.

DSA Address

Computer name the MTA is running on. This is used to build a Presentation Address for the DSA.

MTA Run Directory

Runtime directory for Exchange Server components, usually C:\Exchsrvr.

Max concurrent XAPI applications

Maximum number of concurrent XAPI applications. This is summed together with the existing registry parameters for maximum number of LanMta connections and Administrator clients to give the total number of LTAB entries, that is, the maximum number of (duplex) connections to/from other servers.

Max RPC calls outstanding

Maximum number of RPC threads. This limits the maximum number of RPC procedure calls that are guaranteed to be able to be processed at one time. Used by RpcServerUseAllProtSeqs() and RpcServerListen().

Min RPC Threads

Minimum number of RPC threads. This identifies the minimum number of call threads. Used by RpcServerListen().

RPC Authentication Level

RPC authentication level. This identifies the level of authentication to use over outgoing RPC connections.

Dispatch remote MTA messages

Used by development to allow for the replaying of a saved MTA database on a different machine.

Text Event Log

Used to send the Event Log messages to text files as well as to the NT Event Log. Useful for gathering log information for sending back to development upon request.

Handle Exceptions

Forces the MTA to handle unexpected exceptions in the code and dump out debug information. Should only be used when requested by development for tracking a particular problem.


Microsoft Exchange Server Schedule+ Registry Reference

This section provides the details on the registry settings used by Schedule+.

The following rules apply to these registry keys.

  • For Boolean keys, zero or no value means false, non-zero means true.
  • The default is zero, false, or empty unless otherwise noted.
  • Default values are absent from .ini files unless otherwise noted by the comment "(always present)", meaning after exiting Schedule+ online once.
  • Supported color values are 1 through 16 inclusive.

Caution You should not change any of the Microsoft Exchange Server registry key values unless you are familiar with the full effect of the change.

Under Registry Key:
Hkey_local_machine\Software\Microsoft\Schedule+\Application

Name | Type | Default Value | Description
AutoScanDisabled | REG_DWORD | 0 | 1 – autoscan disabled, 0 – autoscan enabled Setting this registry key to 1 turns off all background processing of Schedule+ mail, including Auto-Accept, Auto-Delete, Auto-processing of responses (including deletion of silent responses), and Auto-forward (for MS Mail clients).
PollTime |  | 600 | Number of seconds between polling intervals.
LocalUser |  |  | (Should always be present.)
LocalPath |  |  | Path where the local Schedule+ file exists. (Should always be present.)
AppPath |  |  | Path where Schedule+ exe will be found initialized by the setup program, or when App runs.
CDPath |  |  | Path where the DLLs are located. Setup program initializes this. Will be different from AppPath if the user chooses to install in "Run from CD" mode, in which case we only install the .Exe on the local drive.
OfficeInstalled |  |  | Set to 1 if Schedule+ was installed with Microsoft Office.
MailDisabled |  |  | Do not attempt to load and start MAPI and open a server file
FormsRegistered |  |  | Indicates that the MAPI forms have been registered.
ServerPath |  |  | Path to server, for example, \\davewh5server\po
TransportList |  |  | Name of transport list, for example, Xpt.xpt
ScheduleFinders |  |  | Names of transport DLLs, such as Mstre
ScheduleInterfaces |  |  | Names of interface DLLs, such as Msscd
DefaultLocalPath |  |  | Primer path for 'choose local path' dialog at initialization time.
PrimaryServer |  |  | Indicates whether you should give the user the option to choose a local file.
WatchInstalled |  |  | Indicates watch export DLL installed.
OptionsTab |  |  | The last options tab selected by user.
OptionsFilePath |  |  | If this exists, it must be a valid path that points to a VUE file. Otherwise, the username is used to create a VUE file that resides in the Windows directory.
RecoverAll |  |  | Indicates that header errors should be treated as file corruptions rather than version errors. When the file header is corrupt the file may look like it is not a Schedule+ file. Normally the code treats this as a foreign file type and does not try to recover the file. When this key is set to 1, the code treats the file as if it were corrupt.
ApptBookLinesColor |  |  |
GridLinesColor |  |  |
GridTextColor |  |  |
TentativeApptColor |  |  |
Ex-Import Stuff |  |  |
ExportRange |  |  | Default: All (entire file)
ImportNoDupCheck |  |  | If set to 1, greatly speeds up CSV imports by not checking for duplicates.
ImportNoDupCheck |  |  | k ; if ; if set to 1, greatly speeds up CSV imports by not checking for duplicates
ImportDoNotAsk AboutConflicts |  |  |
ArchiveFile |  |  | Archive path/filename
ExportFile |  |  | Most recent export path/filename
ReminderToTop |  |  | Default: 5 (in minutes) to bring reminders to top, range 1 - 60 inclusive
SchdplusReminder |  |  | Default: ".\Msremind.wav" (name of reminder wave file)
NewTaskGridIgnoreNoDueDate |  |  | Whether to exclude tasks with no due date (useful for daily reminder)
GridAutoFit |  |  | Resize columns to fit when resizing window/grid
DemosEnabled |  |  | Whether to allow Demos menu command
DefaultPrinter |  |  | Was the last printer used the default printer? 0/1
LocalPrintFileDir |  |  | Points to the location of the .prt files. no default!
GrayShade |  |  | Default: 230 range is 0 (black) to 255 (white)
PCLGrayPercent |  |  | Default: 15 range is 0 to 100 (%)
NoHPTypeLines |  |  |
NoToolBar |  |  |
NoStatusBar |  |  |
CoverBitmap |  |  | Path to Windows bitmap file
UpdateCover |  |  | Default: 120 (in minutes) between updates of cover page
NoNewContactSpaceJump |  |  | Don't jump from first to last name on space in new contact
DefaultNetPassword |  |  | Default: no default password
SyncStartIdle |  |  | Default: 6000 number of csecs to wait after a user action before continuing synchronization
PrimaryServer |  |  | Default: 0. Working primarily from Server file? This flag only reflects the default setting for new users on the machine. If the user changes this setting, the change will be saved in the profile, not the registry.
ShowRecurInstances |  |  | Default: 1 (most 32)
InitialAccess |  |  | Default: 0 (read_minimal) 1 = none, 2 = read
[Watch Wizard] |  |  |
PhoneShowNormal |  | 0 | Shows names normally (for example, "first last" instead of "last, first"). Note that in most cases we want to show "last, first" because the Watch sorts the textized string that we send it.
[Microsoft Schedule+] |  |  |
PollTime |  |  | Default: 6000 (in centiseconds)
DefaultRemindAgain= |  |  |
DefaultRemindAgain Amount |  |  | Default: 5
DefaultRemindAgain Units |  |  | Default: minutes


Customizing Menus

The following is an example of a customized menu printout.

[Custom Menus]

;Examples
NewMenu=2.0;help;Sample;;;Status for sample;helpfile.hlp;0
NewCommand=2.0;Sample,#-1;Schedule+ Ini;;notepad schdplus.ini;Edit Schedule+
Ini file;helpfile.hlp;0
Sep=2.0;Sample,#-1;;;;;;
tag=version;menu to precede;new menu;DLL name;command string;status
string;help
file;help id
tag Identifies the command to someone reading the INI file,
but serves no other purpose.
version Identifies the version of Schedule+ with which the
command is compatible; 2.0 is the current version.
menu to precede Path to an existing menu. The new menu item will be
added before the menu. The name is case insensitive,
and ampersands are ignored. Commas are used to
specify the path to the menu. To specify an absolute
menu position use '#' followed by the number for the
position. If -1 is specified for the position then
the new menu will be added at the end of menu
specified.
new menu The menu name to be added to the menu bar. As usual,
you may include an ampersand just before the letter
that is to serve as an ALT-key accelerator. If no
name is provided, then a seperator will be added.
DLL name Name or path of the DLL in which the custom command
resides. (DLL not currently supported)
command string Command string passed as one of the parameters to
the DLL entry point for the command. If no DLL name
then the command string will be used to call WinExec.
If no command string or DLL name is provided, then a
new pop-up menu will be added.
status string String displayed on the status bar when the menu item
is selected.
help file Windows help file to be invoked when the user presses
F1 while the command is selected. Passed to the
Windows Help program.
help id Passed to the Windows Help program along with the
help file name. Use -1 (help file index) if there is
no specific entry in the help file for this command.


Deleting Menus

[Deleted Menus]

;Examples
DeleteHelp=2.0;help
DeleteUndo=2.0;edit,undo
tag=version;menu path
tag Identifies the command to someone reading the INI file,
but serves no other purpose.
version Identifies the version of Schedule+ with which the
command is compatible; 2.0 is the current version.
menu path Path to an existing menu to be removed. The name is
case insensitive, and ampersands are ignored. Commas
are used to specify the path to the menu. To
specify an absolute menu position use '#' followed by
the number for the position.


Creating Custom Pop-up Menus

[Custom Popup Menus]

;Examples
NewCommand=2.0;toolbar,#-1;Schedule+ Ini;;notepad schdplus.ini;Edit Schedule+
Ini file;helpfile.hlp;0
tag=version;menu to precede;new menu;DLL name;command string;status
string;help
file;help id

Note Same format as [Custom Menus] section, but use one of the following names.

For pop-up menus:

  • edit, appointments, events, tabs, toolbar, tasks, projects, contacts, columns, navigator

[Deleted Popup Menus]

;Examples
DeleteApptCut=2.0;appts,cut
tag=version;menu path


Microsoft Exchange Server Internet Mail Service Registry Reference

This section provides details on the registry settings used by the Internet Mail Service.

Under Registry Key:
SYSTEM\CurrentControlSet\Services\MSExchangeIMC\Parameters

Name

Type

Default Value

Description

ArchiveFailedMessage
Settings

REG_DWORD

AssertState

REG_DWORD

BadInMessageAction

REG_DWORD

0x1

Set this registry parameter to 1 to save inbound messages that cannot be processed by the Internet Mail Service and have non-delivery reports (NDRs) created to a BAD directory under the IMCDATA\IN directory.

BadOutMessageAction

REG_DWORD

0x1

Set this registry parameter to 1 to save outbound messages that cannot be processed by the Internet Mail Service and have NDRs created to a BAD directory under the Imcdata\out directory.

CommonName

REG_SZ

Internet Mail Service (zoomflume)

ConsoleStatFrequency

REG_DWORD

0x14

Controls how often (in seconds) status is printed to the console; only relevant in console mode.

Debug

REG_DWORD

0

Sets the Internet Mail Service's internal debug level

DebugBoxState

REG_DWORD

DisplayMessageStats

REG_DWORD

0x1

Controls what stats are displayed in console mode.

DisableLoopback
Connections

REG_DWORD

0

The Internet Mail Service allows configurations where SMTP connections are made to itself. There are cases where this behavior is desired, such as when one Microsoft Exchange user addresses another using an SMTP proxy. However, this can also allow loopbacks and inefficient configurations. You can configure the Internet Mail Service so it won't initiate SMTP connections if the destination host's IP address matches its own. Instead, it will create an NDR for the message. To enable the Internet Mail Service's connection loopback detection, set the DWORD registry value to 1.

DisableResolver
SearchList

REG_DWORD

0

If you are using a wildcard MX DNS record, the Internet Mail Service will append the default domain from your TCP/IP configuration to each host name before trying to resolve it in DNS. To prevent this, set the DisableResolverSearch
List value to 1. This setting stops the Internet Mail Service from appending a domain to host names before trying to resolve them.

DiskSpaceLowWater
Mark

REG_DWORD

If disk space falls below this number the Internet Mail Service will enter flush mode until it increases above this number.

EnableMIMEWrap

REG_DWORD

0

EnableMIMEWrap controls word-wrap in outgoing non-TNEF MIME messages. If it is enabled, lines in MIME messages are wrapped at a fixed column. If EnableMIMEWrap is disabled (and UseRTFText is also disabled), lines are wrapped using quoted printable encoding. MIME-enabled readers will unwrap the lines, restoring the original text flow, but users with non-MIME readers will see a "=" character appended to each wrapped line of text. EnableMIMEWrap is enabled by default.

UseRTFText also affects word-wrap. If enabled, text lines in all non-TNEF messages are wrapped at a fixed column, regardless of the setting of EnableMIMEWrap. The word-wrap setting for non-MIME messages on the Internet Mail Service properties in the Microsoft Exchange Server Administrator program is ignored.

ExtensionDLL

REG_SZ

c:\exchsrvr\
connect\
msexcimc\bin\
imcext.dll

Pointer to an Internet Mail Service message routing extension DLL. This value should exist only if an extension DLL is used.

GoodInMessageAction

REG_DWORD

GoodOutMessage
Action

REG_DWORD

HomeDSA

REG_SZ

Internet Mail Service (zoomflume)

IgnoreCommaInFrom

REG_DWORD

If non-zero, unquoted display names with commas are supported in addresses (for Xenix compatibility).

InboundCanonicalization

REG_DWORD

0x1

Obsolete. Not used.

InboundEmailAddress
List

REG_MULTI_SZ

SMTP

Internet Mail Service proxy type.

InboundThreads

REG_DWORD

0x1

Number of threads dedicated to inbound processing.

InOutThreads

REG_DWORD

0x6

Number of threads dedicated to both inbound and outbound processing.

MAPIDeferredErrors

REG_DWORD

MaxReceivedHeaders

REG_DWORD

0x12

Maximum number of hops a message can take before being returned as non-deliverable. This prevents infinite loops from occurring. The number is the count of received headers in the message.

MaxRecipients

REG_DWORD

0

Maximum recipients in a batch

MessageTracking

REG_DWORD

0

Obsolete. Not used.

NoExceptionHandling

REG_DWORD

If present and non-zero, exception handling is disabled

ObjectDefaultPerformance
Data

REG_BINARY

ObjectGUID

REG_SZ

61DF5950
E40A-11ce
A2C9
00AA0040E865

Organization

REG_SZ

OrgUnit

REG_SZ

OutboundThreads

REG_DWORD

0x1

Number of threads dedicated to outbound processing

OutQueueHighWater
Mark

REG_DWORD

0x61a8

When this many messages are queued in the OUT directory, the Internet Mail Service will stop accepting messages.

OutQueueRestartWater
Mark

REG_DWORD

0x3a98

If the Internet Mail Service has stopped accepting messages due to the high water mark being reached, and when the number of messages in the Out directory falls below this number, the Internet Mail Service will start accepting messages again.

PS_ROUTING_Xlate

REG_DWORD

QueueWaitTimeout

REG_DWORD

RootDir

REG_SZ

d:\Exchsrvr\imcdata

RouteRecalculation
Interval

REG_DWORD

0xf

Controls how often the Internet Mail Service checks for GWART updates; if zero it never checks.

SaveBeforeSubmit

REG_DWORD

SaveFailedOutbound

REG_DWORD

If non-zero, outbound messages failing content conversion that have NDRs created are stored in the Content Conversion Failed folder.

SiteDN

REG_SZ

/o=Lazy_D/
ou=Istanbul

SiteDomain

REG_SZ

The domain to be used in the originator address for reports generated by the Internet Mail Service. Overrides the site address.

SMTPRecvTimeout

REG_DWORD

0x12c

SMTP protocol timeout waiting for packet transmission. To never time out, this number can be set to zero. However, this is not recommended because it could cause the Internet Mail Service to stop responding.

SMTPWaitForAck

REG_DWORD

0x12c

SMTP protocol timeout for OK response to a command sent to another host (seconds).

SMTPWaitForBanner

REG_DWORD

0x12c

SMTP protocol timeout for HELLO banner from another host (seconds).

SMTPWaitForData
Block

REG_DWORD

0x258

SMTP protocol timeout waiting for the other host to send the CRLF termination to the data block.

SMTPWaitForData
Initiation

REG_DWORD

0x78

SMTP protocol timeout waiting for the other host to start transfer of the data block.

SMTPWaitForData
Termination

REG_DWORD

0x258

SMTP protocol timeout waiting for a response from the other host to the CRLF data termination.

SMTPWaitForMail
From

REG_DWORD

0x12c

SMTP protocol timeout waiting for a response to the From command.

SMTPWaitForRcpt

REG_DWORD

0x12c

SMTP protocol timeout waiting for a response to the Rcpt command

ThreadsPerProcessor

REG_DWORD

0x3

UseRTFText

REG_DWORD

0x1

UseRTFText specifies if reply-and-forward text is quoted in outgoing non-TNEF. If it is enabled (non-zero), Internet-style quoting is applied to reply-and-forward text by inserting a greater-than sign (>)before each line. If UseRTFText is disabled (set to zero or not present), no Internet-style quoting is applied. UseRTFText is enabled by default.

WarnedAboutTCPIP
Config

REG_DWORD

0x1


Microsoft Exchange Server Setup Registry Reference

This section provides the details on the registry settings used by the Microsoft Exchange Server Setup program.

Caution You should not change any of the Microsoft Exchange Server registry key values unless you are familiar with the full effect of the change.

Under Registry Key:
HKEY_LOCAL_MACHINE\SOFTWARE\MICROSOFT\EXCHANGE\
SETUP

Name | Type |  | Description
InstallPath* | REG_SZ |  | The path to the last install point.
Services* | REG_SZ |  | The path to Microsoft Exchange services.
MSMailConnector* | REG_SZ |  | Same as Services.
Internet* | REG_SZ |  | Same as Services.
X400* | REG_SZ | Same as Services.
Sample Applications* | REG_SZ | The path to the Sample Applications public folder.
Books Online* | REG_SZ | The path to the on-line documentation.
AdminDest* | REG_SZ | The path to the Administrator program.
Build | REG_DWORD | The build number of the setup executable that was run last.

* These keys exist only if the component is installed.


Microsoft Exchange Server System Attendant Registry Reference

This section provides details on the registry settings used by the System Attendant.

Caution You should not change any of the Microsoft Exchange Server registry key values. Severe system problems might occur! You can change some values through the Administrator program. Some values (such as Enterprise, Server, and Site) cannot be changed.

Under Registry Key:
H_KEY_LOCAL_MACHINE/System/CurrentControlSet/
ServicesMsexchangeSA/Parameters

Name | Type | Description
Enterprise |  | The Microsoft Exchange Server enterprise name.
LogDirectory |  | The directory for Message tracking log file.
LogFlushFreq |  | The number of log entries to wait for before writing a message tracking log file to the disk.
OldLogsCleaningInterval(Days) |  | The number of days old message tracking log files will be kept before deleting.
MaintenanceMode/Flag |  | Indicates if maintenance mode is on or off. In maintenance mode, the server monitor will not attempt to restart stopped services. You can enter maintenance mode using the Administrator program command line. For more information, see the Administrator's Guide under "Stopping Monitors for Maintenance."
MaintenanceMode/User |  | Indicates the user who last changed the maintenance mode.
MaintenanceMode/Time |  | Indicates the time at which the maintenance mode was last changed.
Polling Interval |  | The delay in milliseconds between times the System Attendant does scheduled tasks.
Server |  | The Microsoft Exchange Server name.
Site |  | The Microsoft Exchange Server site name.


Microsoft Exchange Server Information Store Registry Key Structure

The following diagram shows the keys created in the registry when the information store is installed by Microsoft Exchange Server Setup.


Microsoft Exchange Server Information Store Registry

Key/Value Hierarchy

EventLog\Application |  |  |
 | MSExchangeIS |  |
 |  |  | CategoryCount
 |  |  | CategoryMessageFile
 |  |  | EventMessageFile
 |  |  | Types Supported
 | MSExchangeIS Private |  |
 |  |  | CategoryCount
 |  |  | CategoryMessageFile
 |  |  | EventMessageFile
 |  |  | Types Supported
 | MSExchangeIS Public |  |
 |  |  | CategoryCount
 |  |  | CategoryMessageFile
 |  |  | EventMessageFile
 |  |  | Types Supported
MSExchangeIS |  |
 |  | DependOnGroup
 |  | DependOnService
 |  | DisplayName
 |  | ErrorControl
 |  | ImagePath
 |  | ObjectName
 |  | Start
 |  | Type
 | ParametersPrivate |
 |  | Clean Per User Read Interval
 |  | DB Path
 |  | Disabled
 |  | General Event Log
 |  | Log Downloads
 |  | Reread Logon Quotas Interval
 |  | Track Duplicates
 |  | Transport Event Log
 | ParametersPublic |
 |  | DB Path
 |  | Disabled
 |  | General Event Log
 |  | Log Downloads
 |  | Maximum Cached Categorizations
 |  | Maximum Cached Restrictions
 |  | Read PF Instances Interval
 |  | Read PF Settings Interval
 |  | Replication
 |  | Replication Backfill Timeout (Solicited)
 |  | Replication Backfill Timeout (Unsolicited)
 |  | Replication DS Updates
 |  | Replication Event Log
 |  | Replication Expiry
 |  | Replication Folder Count Limit
 |  | Replication Message Count Limit
 |  | Replication RMR Timeout
 |  | Replication Send Folder Tree
 |  | Replication Status Updates
 |  | Replication Timeout
 |  | Track Duplicates
 |  | Transport Event Log
 | ParametersSystem |
 |  | Aging Clean Interval
 |  | Aging Keep Time
 |  | Circular Logging
 |  | DB Log Path
 |  | DB Recovery
 |  | DB System Path
 |  | DS Computer
 |  | Max Threads
 |  | MTA Computer
 |  | Online Compaction
 |  | Reread GWART Interval
 |  | Reread IS Quotas Interval
 |  | Synch Mailbox/Check OOF Interval
 |  | This Server
 |  | Working Directory
 | Performance |
 |  | Close
 |  | Collect
 |  | First Counter
 |  | First Help
 |  | Last Counter
 |  | Last Help
 |  | Library
 |  | Open
 | Security |
 |  | Security


Chapter 7 Troubleshooting MS Exchange Server

This chapter discusses ways to troubleshoot or prevent certain problems in your organization. It is organized into the following sections:

  • Improving TCP/IP Startup Times
  • Accessing the Registry After Problems Are Reported
  • Backing Up Inbox Assistant Rules


Improving TCP/IP Startup Times

When starting the Microsoft Exchange Client, one of the more common reasons for slow startup is the failure to resolve the Microsoft Exchange Server Transport Control Protocol/Internet Protocol (TCP/IP) host name. This section outlines a procedure for eliminating host name resolution problems on client computers running TCP/IP.

Note Before troubleshooting TCP/IP, make sure the Microsoft Exchange Client is not running.

To troubleshoot TCP/IP

In Control Panel, double-click the Mail icon.

In the Services tab, select Microsoft Exchange Server.

Choose Properties.

In the General tab, type the correct Microsoft Exchange Server name and the mailbox name.

Choose Check Name.

After you have verified that the server name and mailbox name are correct, and choose Check Name, you can determine how much time it takes to resolve the name. If it takes more than 30 to 40 seconds to resolve the name, read the following sections to improve startup times.


Improving Startup Times

To improve startup time and performance, follow the steps below, keeping in mind that the host name is resolved in the following order over TCP/IP.

Hosts file

DNS server

NetBios cache

WINS server

Broadcast

LMHOSTS file


Step One: Replace Server Name with IP Address

Use the following procedure to test name resolution and to ping the server computer.

To replace the server name with an IP address

In Control Panel, double-click Mail.

In the Services tab, select Microsoft Exchange Server.

Choose Properties.

In the General tab, type the Internet Protocol (IP) address rather than the server name.

Choose Check Name.

This procedure will test name resolution, and it will also initiate a basic remote procedure call (RPC) ping to the Microsoft Exchange Server computer. The ping utility determines whether a network path can be made between two computers (TCP/IP only).

IP Address Fails to Resolve

If the IP address fails to resolve to the correct Microsoft Exchange Server name, there is either a problem with the RPCs to the Microsoft Exchange Server computer, or with the IP address of the Microsoft Exchange Server computer.

At the command prompt, try to ping the IP address of the Microsoft Exchange Server computer. If this fails, there may be a networking issue or a TCP/IP configuration issue that is preventing connection to the Microsoft Exchange Server computer. This issue must be resolved before the client can connect to the server over TCP/IP.

If a ping of the IP address is successful, but a profile checkname fails to resolve the IP address, then the RPC binding order may be incorrect. Verify that the RPC binding order includes ncacn_ip_tcp first in the list.

IP Address Resolves

If the IP address resolves to the correct Microsoft Exchange Server computer name quickly, then continue with Step Two, below.


Step Two: Ping the Server Name (Host Name Resolution Troubleshooting)

At this point, the Microsoft Exchange Server computer is available for connection through the IP address. The next step is to verify the host name resolution. At the command prompt, ping the Microsoft Exchange Server computer name.

Ping Succeeds

If pinging the Microsoft Exchange Server name works in a timely manner, but the Client starts up slowly, the RPC binding order may need to be modified. For more information, see Knowledge Base article Q136516, "Improving Windows Client Startup Times."

Ping Fails

Run IPCONFIG /all (or WINIPCFG on Windows 95) and check for an address in the DNS entry box. The Domain Name Service (DNS) can be set for all TCP clients through the dynamic host configuration protocol (DCHP), or by using the TCP configuration in Control Panel for the individual computers.


Step Three: Ping the DNS IP Address (DNS Configuration Troubleshooting)

If IPCONFIG displays an IP address in the DNS Servers box, the client computer is configured to resolve host names through the DNS.

The next step in troubleshooting is to verify that the DNS server is available. At the command prompt, ping the DNS IP address. If the DNS does not respond to the request, additional attempts are made at 5–, 10–, 15–, and 20–second intervals. This is the design of DNS and is usually the cause of slow client startup.

Ping to DNS Server Fails

If the client computer is configured for a DNS server that is not available, then DNS either needs to be disabled or configured for a DNS server that is available at all times.

Ping to DNS Server Succeeds

If the DNS server is available and configured properly, the Microsoft Exchange Server computer name and IP address need to be added to the DNS database. After this is done, pinging the Microsoft Exchange Server computer name will resolve to an IP address by the DNS server, enabling faster startup times of the Microsoft Exchange Client.


Adding the Microsoft Exchange Server Computer to the Hosts File

The Hosts file is read every time a Windows Sockets (Winsock) application attempts to resolve a host name. There are no #PRE options to preload entries (LMHOSTS). You can add the Microsoft Exchange Server entry to the Hosts file and then try again without having to restart Windows. The Hosts file on Windows 95 is located in the Windows directory. On Windows NT, it is located in the Windows\System32\Drivers\Etc directory.


Accessing the Registry After Problems Are Reported

If you encounter an error message that indicates Microsoft Exchange Server cannot access the registry, it is most likely because an incorrect value has been detected in this single instance and the registry couldn't be updated.

To resolve this problem, delete the instance and then add it back.

Note If you are concerned that you might be deleting a critical element from your program, call Microsoft technical support before making any changes.

Deleting the instance removes the old instance and enables you to start over. However, sometimes deleting an instance that has a corrupt registry entry may not be successful. You can follow up by performing the following steps.

Stop the external instance from the Control Panel\Services dialog box.

Remove the instance name from the following registry value:

CurrentControlSet\NT External\Linkage\Export" MULTI_SZ

Delete the following instance key from the registry:

CurrentControlSet\<Instance Name>

This will completely remove the external instance.


Backing Up Inbox Assistant Rules

You can back up rules that users have specified while using the Inbox Assistant in the Microsoft Exchange Client. In some cases, users have specified a large number of rules in their Inbox Assistant. While these rules are simple to recreate, it is easier to back up the rules after they have been set. Then the rules can be restored as needed.

The following steps describe how to copy all of your Inbox Assistant rules to a personal folder file (.pst). After you complete these steps, you can remove the Personal Folder service and store the .pst file in a safe location. If you lose your Inbox rules, you can restore them from that .pst file.

To copy your Inbox Assistant rules to a personal folder file (.pst)

Create a .pst file.

Create a folder within the new .pst.

Select the new folder in the new .pst.

From the Tools menu, choose Application Design, and then select Copy Folder Design.

In the Copy Design From dialog box, select your server Inbox.

Select Rules.

Choose OK.

This copies all your Inbox rules to the new .pst. You can now remove the Personal Folder service and store the .pst in a safe location. If you lose your Inbox rules, you can restore them from the new .pst.


MS Exchange Tools

Microsoft Exchange and Microsoft Mail provide a variety of tools that can be used to troubleshoot problems and automate tasks in your organization.

Note These tools are in the Exchange directory on the BackOffice Resource Kit II Utilities compact disc.

The following Microsoft Exchange tools are covered in this chapter:

Microsoft Exchange tools

  • Administrative Mailbox Agent
  • ASpiriN Tool
  • AT & T Mail Migration Wizard
  • AutoFill Tool
  • AutoSig Tool
  • Backup Tool for Microsoft Exchange
  • Buddy Dropper Tool
  • Bulk Advanced Security Tool
  • Cleansweep Tool
  • Crystal Reports
  • DL Import Tool
  • Duplicate Proxy Tool
  • EFD Handcode Agent
  • Event Log Scan Tools
  • Global Send Options Tool
  • Internet Mail Service Sample Extension DLL
  • Import Header Tool
  • Internet Idioms Tool
  • Mailbox Cleanup Agent
  • Mailbox Migration Tool
  • Mailbox Statistics Tool
  • Mailstorm Tool
  • Management Chain List Tool
  • Mapindl Tool
  • MAPIsend Tool (formerly Command-Line Mail Sender—Sendmail.exe)
  • Microsoft Exchange Preview Pane Extension
  • Microsoft Mail Export Tool
  • Microsoft Mail Proxy to Microsoft Exchange Proxy Conversion Tool
  • Microsoft Mail Route Change Program
  • Microsoft Mail SMTP Gateway Proxy Migration Tool
  • Microsoft Schedule+ Address Book Assistant
  • Natural Language Support Configuration Tool
  • ONDL Tool
  • PFAdmin Tools
  • PFTreeInfo Tool
  • Phone Book Search Tool
  • Pkicker Tool
  • Profgen Tool
  • Replver Tool
  • RPC Counter Tool
  • Self-Certification Form
  • Sentinel Tool
  • Server Space Client Extension Tool
  • Simple Mail Handler Tool
  • SwitchForms Tool for Microsoft Outlook
  • UNIX Mail Source Extractor Tool


Disclaimer

The Microsoft Exchange Server tools are not officially supported. Microsoft does not guarantee the performance of the tools, response times for answering questions, or bug fixes to the tools.

The tools are provided "AS IS" without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties for commercial or home use, and/or fitness for a particular purpose. Using these tools with a different language version of Microsoft Exchange Server may produce unpredictable results. The entire risk arising out of the use or performance of the tools remains with the user.


Administrative Mailbox Agent

The Microsoft Exchange Server Administrative Mailbox Agent enables you to create and delete Windows NT accounts and Microsoft Exchange accounts. When you send a request to the Administrative Mailbox Agent, the Agent (running on a Windows NT Server computer with the appropriate permissions) creates a Windows NT account and the associated Microsoft Exchange account. After the Windows NT account is created, the Agent sends you a confirmation message.

Note The Agent can only create Windows NT accounts if requests are received from Microsoft Exchange administrators with the appropriate permissions. For more information on how to grant the required permissions, see "Granting Access Permissions" later in this document.

The Administrative Mailbox Agent consists of a Microsoft Exchange Server application known as the Mailbox Agent. This application is implemented as a Windows NT service that runs on a Windows NT server. Its status as a Windows NT service enables it to run unattended. Note that the Agent does not need to run on the same Windows NT Server computer as the Microsoft Exchange Server computer.

The Microsoft Exchange Administrative Mailbox Agent has its own mailbox on the Microsoft Exchange Server computer where it is installed. It uses this mailbox to receive requests from administrators and users and to send back confirmations and error messages. The Microsoft Exchange Address Book contains an entry (Admin Agent) that you can use when addressing mail to the agent.


Installing the Administrative Mailbox Agent

The Administrative Mailbox Agent is installed through a simple graphical setup program similar to that of a Microsoft Windows setup program.

To install the Administrative Mailbox Agent

In the Exchange\<operating system\platform>\Admin\AdminAgt directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, double-click Setup.exe.

Select the Windows NT Server computer that you want to install the service on. Your current server computer is the default server. After you select the server, the installation program replicates the sites in your Microsoft Exchange organization.

Select the Microsoft Exchange site where you want to install the Administrative Mailbox Agent.

You will be prompted to select the Microsoft Exchange directory container you want to use for the Agent. Select the top-level Recipients container. This opens the Install dialog box.

In the Install dialog box, type or select the directory display name that the user and administrator will see in their Microsoft Exchange Client and the Microsoft Exchange administrator program that you want to send mail to or configure properties for. The recommended name is "Admin Agent."

Select the Windows NT service name that you want to appear in the list of services running on your server. (You can view this list by double-clicking Services in Control Panel.) You can use the same name as the directory display name (Admin Agent).

Select the service account you want to use. You can use the Administrator account or create a special service account with full Windows NT and Microsoft Exchange permissions. Note that this account must have Administrator permissions for the Microsoft Exchange Administrative Mailbox Agent and for Windows NT. If you want to create Window NT accounts on another domain, the other domain must contain these accounts as well, and must have the same password.

Type the service password that corresponds to the service account.

Select the directory where you want to install the Administrative Mailbox Agent. Although you'll need to select a directory on a drive with at least 1 MB of free space, note that the Administrative Agent takes very little space (less than 500K).

After the Administrative Mailbox Agent is installed in the specified directory, you can start the service by using the Control Panel, or by typing Admin Agent at the command prompt. After the Agent starts, it is ready to respond to e-mail requesting the creation or deletion of accounts.


Using the Administrative Mailbox Agent

To use the Administrative Mailbox Agent for creating new accounts, send a message to the Administrative Agent with "NEW" as the subject heading. The body of the message must include the Windows NT account name, and the first and last names of the new Microsoft Exchange user.

To create new accounts

In the Microsoft Exchange Client Viewer, open a new message.

In the message, choose To, and then select the name of the Agent from the Address Book. For example, if you chose the name "Admin Agent" for the Agent during installation, then this name will appear in the Address Book.

In the Subject box, type NEW.

If you are administering more than one messaging container, type the name of the container in X.500-style notation. For example, if you want to request a new user for the container "/cn=Recipients/cn=Office1042," type NEW /cn=Recipients/cn=Office1042 in the Subject box.

In the message body, type one or more lines in the following format:

<Windows NT account name>,<Microsoft Exchange first name>,<Microsoft Exchange last name>

The following figure shows a request for a new account for Bill Lee.

If you have more than one container to administer, the message sent will include the container name after the word "NEW" in the Subject box.

After you send your request, the Administrator Mailbox Agent creates Windows NT and Microsoft Exchange accounts with the specified Windows NT account names and corresponding first and last names.

If you have permission to use the Agent, a confirmation message is sent, as shown in the figure below. This message lets you know that the accounts have been created. As mentioned earlier, you must have the appropriate permissions to create accounts with the Administrative Mailbox Agent. If you do not have permission to create accounts, a message is returned stating that fact.

Deleting Accounts

To use the Administrative Mailbox Agent for deleting new accounts, send a message to the Agent with the word "DELETE" in the Subject box and message body text that contains the name of the Windows NT account and the first and last name of the new Microsoft Exchange user.

Granting Access Permissions

The Administrative Mailbox Agent needs to know which administrators have the access permissions required to request the creation or deletion of accounts. You can grant access permissions to other administrators by using the Admins.csv file.

The Admins.csv file is usually located in the directory where the Administrative Mailbox Agent was installed (for example, C:\Admin). Note that the directory where Admins.csv is stored must be indicated somewhere in the system path for Microsoft Exchange Server to find it.

To add the Admins.csv directory to your system path

In Control Panel, double-click the System icon.

Select the Environment tab, and then type the directory path in the Variable box.

To ensure that the directory path is added to your system path, choose Set.

The Admins.csv. file is a text file that contains a record for each administrator in comma-separated-value (CSV) format. This file can be edited in Notepad or any other text editor. You can also edit Admin.csv by using Microsoft Excel (which natively handles CSV files), as shown in the figure below.

Admins.csv Fields

  • Display Name — The first field for each record includes the display name of each administrator. If the administrator's name is "Lee, Bill," then the first field on the line should read "Lee, Bill." The quotation marks are necessary due to the embedded comma, but if you are editing in Microsoft Excel, Microsoft Excel places the quotation marks around the field automatically.
  • Server — The second field displays the name of the Microsoft Exchange Server computer that all the administrators' accounts are stored on.
  • Recipients Container — The third field displays the Recipients container for all users. When working in this field, use X.500-style directory notation. For example, to place users in the top-level Recipients container, type /cn=Recipients.

    To place users in the container called "Office1," type /cn=Recipients/cn=Office1.

  • Windows NT Domain — The fourth field displays the Windows NT domain that you want to create Windows NT accounts in, or link to. If this field is left blank, the current Windows NT domain for the Microsoft Exchange Server computer is assumed.
  • Permissions Levels
    • Level 3: Set the permissions level to 3 if you want to enable an administrator to delete Windows NT and Microsoft Exchange accounts with the Administrative Mailbox Agent
    • Level 2: Set the permissions level to 2 if you want to enable an administrator to create Windows NT and Exchange accounts with the Agent.
    • Level 1: Set the permissions level to 1 if you want to enable an administrator to link to previously created Windows NT and Exchange accounts, but not to create or delete accounts with the Agent.

    Note You can enter the same administrator's name more than once in the Admins.csv file. In fact, you need to do so if the administrator is responsible for more than one container. However, this forces the administrator to send requests that specify which container to use.

The next figure shows the same Admins.csv file in Notepad format. Note that the first line of column headings is optional. Include this line if you want to clarify the type of information in each field.

To start or stop the Administrative Mailbox Agent

In Control Panel, double-click the Services icon.

Select the Administrative Mailbox Agent from the list of services, and then choose Start or Stop.


ASpiriN Tool

The ASpiriN tool enables you to conveniently view and browse X400 ASN.1 data by using the ASN.1 X400 templates from the Microsoft Exchange Server message transfer agent (MTA).


Installing ASpiriN

To install ASpiriN

  • From the Exchange\<operating system\platform>\Admin\Aspirin directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Aspirin.exe to your computer.


Using ASpiriN

To run ASpiriN

From the Start menu, choose Run, and then choose Browse to search for the folder or subdirectory where you copied the file.

Select the Aspirin folder, and then select Aspirin.exe.

To open a hexadecimal or binary-format ASN.1 file

From the File menu, choose Open.

Select Hex if the file contains ASN.1 data encoded as hexadecimal ASCII.

Select Binary if the file contains ASN.1 data encoded as raw binary.

To produce ASN.1 data files from a Microsoft Exchange Server MTA log file

  • The Microsoft Exchange MTA logs messages and other information in the Exchsrvr\Mtadata directory as BF*.log files. These files contain, among other pieces of data, ASN.1 hexadecimal dumps of messages passing through the MTA. These ASN.1 blocks can be viewed by using ASpiriN if they are parsed out of a BF*.log file. To view these ASN.1 blocks, using the following procedures:

    From the File menu, choose Parse MTA Log.

    Select a log file, such as Bfo.log, and then choose OK.

After you follow the steps above, ASpiriN produces one hex file in the same directory as the log file for each block in the log file. Some, but not all blocks, are ASN.1 data. You can view the ASN.1 hex files by following the procedure outlined earlier.


Troubleshooting ASpiriN

If you have problems during ASN.1 decoding, a message should appear describing the problem. If applicable, you are prompted to choose whether you want the decoder to attempt to continue. Continuing does not guarantee that the decoding will be successful.

If a decoder error is produced, verify that:

  • You have access permissions on the ASN.1 data file
  • The selected file is actually ASN.1 data
  • You chose the correct data format (hexadecimal or binary). If one format didn't work, try the other.

If you have problems parsing an MTA BF*.log file, verify that:

  • You have permissions to create files in the BF*.log's directory.
  • You have disk space available to create additional files.
  • The log file is not obviously corrupted.
  • The log file is not empty.


AT " T Mail Migration Wizard

AT & T Mail Migration Wizard

The AT&T Mail Migration Wizard (Attmwiz.exe) migrates Microsoft Access and PMX mail messages into a local Microsoft Exchange Client personal folder or the Microsoft Exchange Server-based mailbox. This wizard supports AT&T Mail Access Plus version 2.7 and earlier, AT&T PMX Starmail, AT&T PMX PC, and AT&T PMX Term. The mail is still accessible in the native environment.

To run the AT & T Mail Migration Wizard (ATTMWIZ), you must have the Microsoft Exchange Client installed, plus one of the following operating systems:

  • Microsoft Windows version 3.1
  • Windows for Workgroups 3.11
  • Windows 95
  • Windows NT 3.51 or later


Installing ATTMWIZ

To install the ATTMWIZ tool

  • From the Exchange\<operating system\platform> \Migrate\Attmwiz directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Attmwiz.exe to your computer.


Using ATTMWIZ

The AT&T Mail Migration Wizard assumes that the Microsoft Exchange Client profile is in place before migrating messages. If the profile is not in place, the wizard asks that a profile be created. The user name and Microsoft Exchange Server name (and password, for Windows for Workgroups or Windows 3.1) are needed to gain access to the server-based message store.

The Access PLUS and PMX message files should be available locally or on an MS-DOS compatible network drive. If the mail directory resides on a network system that cannot be reached, copy the files to your local drive using a network utility such as File Transfer Protocol (FTP).

When you migrate PMX mail, file names greater than eight characters are truncated. Also, PMX files must be transferred in binary mode, otherwise the file format is corrupted during the transfer.

Note If you use a remote network to store personal folders, the network connection must be started before logging into the associated profile.

Encrypted Messages

All encrypted messages must be decrypted prior to performing the migration process. The AT&T Mail Migration Wizard cannot decode encrypted messages.

To migrate mail messages

In the Choose Source Directory box, enter the path that contains the mail messages for Access PLUS 2.7 or PMX. The default selection is C:\Attmsg.

To migrate mail into an existing folder, select Put messages into existing personal folders, and then select an existing Microsoft Exchange Client mail delivery location. The mail delivery location can be a server-based store or a personal folder.

To migrate mail into a new folder, select Put messages into new personal folders, type a path and file name for the new personal folder, and then choose Next.

Verify that the options selected are accurate, and then choose Convert.

If you are placing the migrated mail in a new folder, supply the information requested to further define the new personal folder. For more information, choose Help.

When the migration process starts, the Access PLUS and PMX mail messages are migrated to the selected location.

Migrating Electronic Forms

One of the special message types migrated from Access PLUS and PMX is the electronic form, which uses protected fields. When forms are migrated to the Microsoft Exchange Client, they lose their functionality. If the form is mailed back to another recipient, the recipient receives a message containing only text, without the ability to enter values into fields. You need to recreate your forms using the Microsoft Exchange Forms Designer.

Addressing Issues

Because Microsoft Exchange Server addresses messages differently from the typical "bang" (!) style addresses, you cannot reply to a message that was migrated from Access PLUS or PMX. If you reply to a migrated message, a non-delivery report (NDR) is returned to the sender.

To restart an interrupted migration or to migrate messages that arrive after the migration

Restart the AT&T Mail Migration Wizard.

The AT&T Mail Migration Wizard determines that a previous message conversion has been attempted and prompts you to choose whether it should process all messages again.

Choose No to convert only those messages that were not converted during the previous migration. If you choose Yes, you may receive duplicate messages if multiple migrations are needed.

Note After a migration has been completed, subsequent migrations can result in duplicate messages.

Migration Summary Information

After the migration is complete, a Summary box displays the number of messages processed and the number of messages logged. This can be helpful in ensuring that all of the messages were migrated to the Microsoft Exchange Client.

In the Summary box, choose View Log to view a file that logs which messages or files were not processed, start and end times, and other information.

Messages that were located in an Access PLUS or PMX Out folder are stored in a new Microsoft Exchange Client personal folder called Converted Out. Messages in the Access PLUS or PMX In folder are stored in a personal folder named Inbox.

Improving Migration Performance

The following tips may decrease the time it takes to migrate messages.

  • If the Access PLUS or PMX messages are located on a network drive, the migration process runs much slower, depending on network traffic. To avoid an unnecessarily long migration process, copy the source message directory tree to the local hard disk.
  • If the personal folder you are migrating messages to is located on the network, consider moving it to a local drive during the migration process.


Troubleshooting the AT " T Mail Migration Wizard

Troubleshooting the AT&T Mail Migration Wizard

The following sections describe how to troubleshoot problems that occur during migration.

Unable to Log On to the Migration Wizard

If there are problems logging on to the AT&T Mail Migration Wizard, verify that you can log on to the Microsoft Exchange Client by using the same profile. If the logon process is successful, restart Windows.

Invalid Directory Message Is Displayed

The AT&T Mail Migration Wizard expects to find the source mail messages under the default directory of C:\Attmsg. Specify where the Access PLUS or PMX messages are located when running Attmwiz.exe, or move them to C:\Attmsg.

Not All Drives Appear in the Browse Dialog Box

If you choose Browse and the appropriate network destination does not appear in the list, make sure that:

  • The network is started.
  • Physical network connectivity still exists

Mail Messages Are Not Migrated to the Microsoft Exchange Client

If the source mail system was PMX, verify that when the files were transferred from the PMX server, it was done using binary mode. If the files are transferred in ASCII mode, portions of the files lose formatting. This can result in messages not being transferred or being transferred incorrectly.

More Messages Are in the Old Client Than in the Microsoft Exchange Client

If not all mail messages are transferred, it can be caused by the following:

  • Messages are corrupt.
  • Messages are not transferred correctly from the source system.
  • Messages are queued (they are logged but not migrated).

To obtain a list of messages that were not migrated, see Attmwiz.log, the summary log file located in the Windows directory. The Attmwiz.log file can be viewed in a text editor such as Notepad.

Some Folder Names Are Truncated

Folder names can be truncated if the source mail system is PMX. The AT&T Mail Migration Wizard truncates folder names to eight characters during migration to the Microsoft Exchange Client. You can restore the long folder names after migration by choosing Rename from the File menu.

Messages Are Not Processed

If all messages are not processed, review the Attmwiz.log file in the Windows directory using a text editor such as Notepad. Review the list of messages. If an error description of "File could not be opened" exists, run the migration again. This error may be cause by a network interruption during processing.


AutoFill Tool

The AutoFill Tool assists in resolving the display names you type in the To and Cc boxes of a mail message in the Microsoft Exchange Client.

When you check names (from the Tools menu, choose Check Names), names that are resolved successfully are added to the AutoFill list. This creates a list of names that you send mail to. AutoFill uses the list to guess the name after a few characters have been typed, and enters the remainder of the recipient's name automatically.


Installing AutoFill

Use the following procedure to install Autofill.

To install Autofill

From the Exchange\<operating system\platform>\Client\Autofill directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, run Setup by typing:

setup [/Ppath /Llocation]

where path is the destination path for the installation (the default is C:\AutoFill32), and location is the path to Autofill32.dll (the default is the current directory). (For command-line Help, type Setup /?).

For example, you can use the following syntax to install AutoFill into the C:\Exchange\AutoFill directory. and copy AutoFill32.dll from E:\Tools\Autofill.

setup /PC:\Exchange\AutoFill /LE:\Tools\Autofill

Close and restart the Microsoft Exchange Client.


Using AutoFill

After the Autofill tool is installed, it runs automatically. However, AutoFill needs to build the list of frequently used names before it can guess a name. For example, the first time you type a name, nothing will happen; however, the next time (after check names has run) when you type the first letter, AutoFill guesses the name.

To delete names from the AutoFill list

  • Using a text editor, delete the name from the Names.dat file.

Registry Settings

The following registry settings are used by AutoFill. If you modify a registry setting to customize AutoFill, you must restart the Microsoft Exchange Client.

Field name | Type | Description
bAliasNm | REG_DWORD | This value can be defined by the user. If set at 1 (true), AutoFill stores the Alias names in the users list of saved names.
bAlways Guess | REG_DWORD | This value can be defined by the user. 1 AutoFill32 guesses the name while you are backspacing. 0 Backspace functions normally.
BDisplayNm | REG_DWORD | This value can be defined by the user. If set to 1 (true), AutoFill stores the display names in the user's list of saved names.
bExactMatch | REG_DWORD | This value can be defined by the user. If set to 1 (true), AutoFill only guesses a name if it is unique. If set to 0 (false), AutoFill gives a best guess.
Data File | REG_SZ | This value can be defined by the user. The name and location of the text file AutoFill uses to store the display names.
Fields | REG_DWORD | This value cannot be defined by the user.
Query Depth | REG_DWORD | This value can be defined by the user. The number of characters that are typed before AutoFill guesses the name.
Tbl Depth | REG_DWORD | This value cannot be defined by the user.

To change the number of characters to wait before AutoFill guesses names

  • Modify the Query Depth registry value. If Query Depth is set to zero, AutoFill guesses after the first character is typed. If Query Depth is set to a non-zero value, AutoFill waits until that number of characters are typed before guessing.

To keep AutoFill from loading

  • Remove the AutoFill32 registry key from the following location:

    Software\Microsoft\Exchange\Client\Extensions

    This registry key registers the AutoFill extension with the Microsoft Exchange Client.

To set AutoFill to guess only if the characters entered map to a unique name

  • Set the bExactMatch registry value to 1 (true).

To set AutoFill to guess while backspacing

  • Set the bAlways Guess registry value to 1 (guess).

    If this value is set to 0, AutoFill does not guess while backspacing.

    Note If you set AutoFill to guess while you backspace, the tool highlights text that you backspace over. This means that the text is erased if AutoFill cannot make a guess or when you press the Delete key.

To set whether the display name or alias name is stored

  • To store the display name, set bDisplayNm to 1 (true). To store the alias name, set bAliasNm to 1 (true). You can set both registry settings to true to store both names.


AutoSig Tool

The AutoSig tool consists of a registry file that solves the problem of the Microsoft Exchange signature block not roving with roving users. It uses the Microsoft Windows 95 profile reconciliation engine to sync the "windir"\autotext signature with the "home"\config\autotext.sign.


Installing AutoSig

Installing the AutoSig tool is a simple process. After installation, you can use the auto signature, because the AutoSig tool automatically adds entries to your registry keys to enable this feature.

To install AutoSig

From the Exchange\Common\Autosig directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy autosig.reg to your Windows\System directory.

From the Start menu, choose Run.

Select Autosig.reg from your Windows\System directory.

Under the [HKEY_CURRENT_USER\Software\Microsoft\Autosig]registry key, AutoSig adds the following new entry: "Path"="C:\\Windows"

Under the [HKEY_CURRENT_USER\Software\Microsoft\Windows\
CurrentVersion\ProfileReconciliation\Autosig] registry key, Autosig adds the following new entries:

"CentralFile"="Config"

"DefaultDir"="*windir"

"LocalFile"="" (blank)

"MustBeRelative"=dword:00000000

"Name"="Autotext.sig"

"RegKey"="Software\\Microsoft\\Autosig"

"RegValue"="Path"


Backup Tool for Microsoft Exchange

The Backup tool for Microsoft Exchange provides an automated way to report whether a backup was successful or if it failed.

To ensure that all of your Microsoft Exchange data is backed up, you should back up the following files:

  • Microsoft Exchange Server Directory files (Dir.edb).
  • Private Microsoft Exchange Database files (Priv.edb).
  • Public Microsoft Exchange Database files (Pub.edb).

This tool prevents you from inadvertently ignoring a failed backup.


Installing the Backup Tool

To install the Backup tool

  • From the Exchange\<operating system\platform>\Admin\Exchbkup subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the Exchbkup.exe file to your computer.


Using the Backup Tool

The Backup tool prevents you from having to manually verify whether all Microsoft Exchange Server backups succeeded or failed. This tool uses a script that searches the Windows NT Exchange backup log files and then reports:

  • Statistics on each Microsoft Exchange Server computer that is backed up.
  • The size of each file backed up.
  • The amount of time each backup took.

This script extracts the data into a Microsoft Excel spreadsheet, which is routed to the daily Microsoft Exchange operations report. Therefore, only one report is needed to provide the backup status for all Microsoft Exchange Server computers.

Sample Output

Each log entry for an attempted backup is in the following format:

Backup Status
Tape Name: "Tape created on 1/10/96"
Backup of "microsoft\usa\CHGO-101-MSG\Directory"
Backup set #1 on tape #1
Backup description: "ON-LINE BACKUP OF CHGO-101-MSG"
Backup Method: Normal

Successful Backup Sample

Backup started on 1/10/96 at 12:20:14 AM.
Backup completed on 1/10/96 at 12:25:34 AM.
Processed 219,955,494 bytes in 5 minutes and 20 seconds.
Tape Name: "Tape created on 1/10/96"
Backup of "microsoft\usa\CHGO-101-MSG\Information Store"
Backup set #2 on tape #1
Backup description: "ON-LINE BACKUP OF CHGO-101-MSG"
Backup Method: Normal
Backup started on 1/10/96 at 12:25:36 AM.
Backup completed on 1/10/96 at 1:25:05 AM.
Processed 2,740,793,728 bytes in 59 minutes and 29 seconds.
Failed Backup Sample
Backup Status
Tape Name: "Tape created on 1/10/96"
Backup of "microsoft\usa\CHGO-101-MSG\Directory"
Backup set #1 on tape #1
Backup description: "ON-LINE BACKUP OF CHGO-101-MSG"
Backup Method: Normal
Backup started on 1/10/96 at 12:56:10 AM.
Backup completed on 1/10/96 at 1:00:51 AM.
Processed 203,178,278 bytes in 4 minutes and 41 seconds.
Tape Name: "Tape created on 1/10/96"
Backup of "microsoft\northamerica\CHGO-101-MSG\Information Store"
Backup set #2 on tape #1
Backup description: "ON-LINE BACKUP OF CHGO-101-MSG"
Backup Method: Normal
Backup started on 1/10/96 at 1:00:51 AM.
The Microsoft Exchange service on \\CHGO-101-MSG\Information Store has
reported an error. Check the event log for more information.
Process Aborted
Backup completed on 1/10/96 at 1:09:07 AM.
Processed 270,958,690 bytes in 8 minutes and 11 seconds.
Note the text:
The Microsoft Exchange service on \\CHGO-101-MSG\Information Store has
reported an error. Check the event log for more information.
Process Aborted


Buddy Dropper Tool

Buddy Dropper (Dropper) enables you to automate files, the registry, applications, and other tasks for an array of Microsoft Windows 95 and Windows NT servers. It helps manage large mixed-platform and mixed-language environments.

When you use the Dropper tool, you can specify a hierarchy of server nodes. A node can be an individual server or a server group. Because each server node contains a hierarchy of actions and Dropper variables, actions are configured by the script creator to perform tasks, and variables enable data to be shared from server to server.


Installing Buddy Dropper

To install Buddy Dropper

From the Exchange\<operating system\platform>\Admin\Dropper subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Dropper.exe and Droprm.exe to your computer.

Copy all dynamic-link libraries (DLLs) to %systemroot%\system32 for Windows NT, or to %systemroot%\system for Windows 95.


Using Buddy Dropper

Use this tool when you want to avoid manual operations while working with a multitude of servers.

To run Buddy Dropper

From the Start menu, choose Run, and then choose Browse to locate the Buddy Dropper directory.

Double-click Dropper.exe.

Automating Tasks

You can use Buddy Dropper to automate the following tasks:

  • Starting applications on all servers.
  • Setting variables on all servers inherited from parents.
  • Running the children sites of all servers.
  • Starting applications on My Lab.
  • Setting variables on My Lab inherited from parents.
  • Running applications on children of My Lab.
  • Starting applications on ntserver1.
  • Uninheriting variables from My Lab, such as
    Directory Name=DropperTest1, System Root=(blank).
  • Setting the COMPUTERNAME reserved variable to ntserver1.
  • Running All Server actions.
  • Running My Lab actions, such as Get System Root path, If we obtained the System Root, and so on (see figure below).
  • Starting application on ntserver2.

Buddy Dropper User Interface

The following figure shows the different panes in Buddy Dropper.

To add a server node

Select a server group to which you want to add a node, for example, All Servers.

From the Edit menu, choose Add Server or Edit.

Select Add Server Group.

To add an action

Select a server node to which to add the action, such as My Lab.

Select an action node, such as All Actions.

From the Edit menu, choose Add Action.

To add a variable

Select a server node to which to add the variable.

Select a variable.

From the Edit menu, choose Add Variable.

If variables are defined both on a parent and on a child of the parent, the child's setting overrides the parent's setting. Siblings inherit "clean" variables from their parents; that is, siblings may not pass data from one to another by using Dropper variables (use temporary registry keys, environment variables, and so on).

Sample Dropper Script Used to Create a Directory

Suppose you have a laboratory that contains several computers. Some are Windows NT Server/Microsoft Exchange Server computers; others are Windows 95 client computers. You want to create a certain directory under the system root directory on the Windows NT servers. You have decided to use Dropper because it will save you a lot of button-clicking, because it has a cooler user interface than the command prompt, and because you're eating lunch in your office and don't want to walk over to the lab.

To create a directory under the system root directory of Windows NT Server, you'll need to do the following (each step is explained in more detail later in this document):

Set up your list of servers and variables. Then, for each computer in the lab, complete steps two through four:

For each computer in the lab, obtain the registry value path for the system root directory on the computer by using the Get Registry Value action. If you can't obtain this key, skip to the next computer.

Obtain the system root path.

Create a directory (of previously defined names) under the system root directory.

Now you're ready to run the Dropper script.

Step One

To set up your list of servers and variables

From the File menu, choose New to create a new Dropper script.

Select All Servers.

From the Edit menu, choose Add Server Group.

Name the group "My Lab," and then choose OK.

Select the My Lab server group.

From the Edit menu, choose Add Server.

Type the name for one of your lab computers, and then choose OK.

Repeat steps 6 and 7 for all computers in your lab on which you want the directory created.

The next step is to create variables to define the behavior of the script.

To create variables

Select the My Lab server group.

Click anywhere in the Variables pane.

From the Edit menu, choose Add Variable.

  • Name = "Directory Name"
  • Value = "DropperTest1"

From the Edit menu, choose Add Variable.

  • Name = "System Root"
  • Value = "" (blank)

Your screen should resemble the figure below.

Step Two

Now you are ready to add a few actions. To do so, you need to obtain the registry value for the system root directory by using the Get Registry Value action, as shown in the following procedure.

To obtain the registry value

Select the My Lab server group.

Select the All Actions node.

From the Edit menu, choose Add Action.

Select Get Registry Value, and then choose OK.

  • Name = "Get System Root path"
  • Server = "%COMPUTERNAME%"
  • Key = "HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\
    CurrentVersion\SystemRoot"
  • Variable = "System Root"

Now you have created an action that will take the System Root path out of the current computer's registry and place the value into the System Root Dropper Variable.

Step Three

Before proceeding further, you need to obtain the system root path.

To obtain the system root path

Select the All Actions node.

From the Edit menu, choose Add Action.

Select Conditionally Execute Action Group, and then choose OK.

  • Name = "If we obtained the System Root"
  • Variable Name = "System Root"
  • Compare = "does NOT EQUAL", "" (variable)

Choose OK.

This action tests the value of the Dropper variable "System Root" with (variable). If the System Root is not equal to (variable), then the children of this action will be executed.

Step Four

Now you need to add the action to create the directory as a child of the conditional action in the last step. Note that this action will only be carried out if the System Root is not blank.

To create the directory

Select the If we obtained the System Root action group.

From the Edit menu, choose Add Action.

Select Create Directory.

  • Name = "Create the Directory"
  • Server = "%COMPUTERNAME%"
  • Directory = "%System Root%\%Directory Name%"

Choose OK.

Your screen should resemble the following figure.

You're done!

Step Five

To run the Buddy Dropper script

From the Run menu, choose Start All.


Dropper Remote Tool

Dropper Remote (DropRm.exe) is a Windows Sockets (WinSock) server application that uses static port allocation (port 1066). The "Run Remote Application" action contains a WinSock client that connects to the specified server and sends a data structure over the WinSock connection. The structure is then decomposed into a command string and several option flags on the remote side, and the application starts. If the application successfully starts and if you have requested the "Wait for completion" flag, DropRm waits until the application has started, and then returns a handshake signal to Dropper by using the active connection. At this point, the Dropper script execution proceeds normally.

Using Dropper Remote

The Dropper Run Remote Application command enables you to run an application on a remote computer, instead of running it on a computer where Dropper resides. This command is useful if:

  • You need to run installation programs for an application on a number of remote computers to upgrade existing software.
  • You need to run batch files on remote computers that perform functions not accessible from remote computers, such as mapping local drives to network shares.
  • You need to run batch files to distribute network load, such as copying very large directory trees.

To install Dropper Remote

If you followed the procedures described earlier in "Installing Buddy Dropper," then you have already installed Dropper Remote. If Dropper Remote is already installed, double-click DropRm.exe to start the program. If you have not already installed Dropper Remote, then follow the procedures below:

Copy DropRm.exe to any directory (preferably a directory in the system path).

Copy the following DLLs to the system directory (%systemroot%\system for Windows95 or %systemroot%\system32 for Windows NT):

  • mfc40.dll
  • msvcrt40.dll
  • wsock32.dll.

Start DropRm.exe.

To use the Dropper Run Remote Application command, the remote target computer of a Run Remote Application action must be running the Dropper Remote file (DropRm.exe), and must use Transport Control Protocol/Internet Protocol (TCP/IP) as the communication protocol.

Note The DropRm application does not need to be running on remote servers if you do not plan to use the Run Remote Application action. To maximize the usefulness of Buddy Dropper, however, it is recommended that DropRm be placed in the startup group of all computers where Dropper will run, so that it is always available. The flat/min can be used when running DropRm to cause it to run minimized (for Help on command-line options, type DropRm /? at the command prompt).

Dropper Run Remote Application action

The following figure shows the configuration tab for a Run Remote Application action.

In this example, the Notepad.exe application is started on all servers where the action applies. The working directory is an optional argument. If it is specified, the application's working directory will be set. If it is not specified, the working directory is the system default directory. Note that if the working directory is specified but does not exist, the application will fail to start.

In the following example, Dropper runs a batch file on the remote computer; the application "cmd.exe" (the Windows NT command prompt) starts with the batch file specified as an argument, and no working directory is set. The /c argument causes the command prompt to exit after the batch file is run.

If you need to have an application completed on the remote computer before continuing the Dropper script, select the Wait for application to complete check box. This causes the Dropper script to stop until the remote application has completed (or has failed to execute).

You can, however, stop the Dropper script during this time. A common situation requiring use of the Wait flag is the mapping of a network share to a local drive. In this case, you would do the following:

If drive X: is currently mapped to a network resource, unmap it by typing the following at the command prompt:

net use /d X:

Map drive X to \\<server\share> by typing:

net use X: \\<server\share>

In this case, the steps must be sequential. Step one must be completed before you move to step two. The Wait flag should be specified in step one. Also, because further actions are likely to depend on the drive mapped by step two, it is suggested that you specify the Wait flag for step two as well.

Example of using Buddy Dropper

In the following example, Dropper is being used to install and upgrade Microsoft Exchange Server testing topologies consisting of 100 or more computers. Computers within the topology are a mixture of Intel, Alpha, MIPS and PowerPC platforms. Each computer has installed one of a dozen or more languages. Each configuration mandates a different set of installation files and settings. The following figure displays these files and settings.

In this example, the following procedures are used:

Obtain the country code for the installed language from the remote computer's registry.

Match the language code to all known languages, and set the lang variable accordingly (lang will then contain the name of a directory based on language type on the install point from which the Setup program is run)

Perform the same procedure for detection of processor type.

Construct the string that indicates the universal naming convention (UNC) path to the appropriate setup.exe for the remote computer's processor type and installed language.

Have the remote computer launch setup.exe from the setup path and with appropriate flags.


Installing the Bulk Advanced Security Tool

To install the Bulk Advanced Security Tool

  • From the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Sectool.exe to your computer.


Using the Bulk Advanced Security Tool

Use the following procedures to decrypt and encrypt messages.

To decrypt messages in a folder

In the Exchange\<operating system\platform>\Security\Sectool directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, double-click Sectool.exe.

From the Exchange Security menu, choose Unsecure Folder.

Type your security password, and then choose OK.

Select the message store containing the messages you want to decrypt, and then choose OK.

Select the folder containing the messages you want to decrypt, and then choose Start Here. To select a subfolder, choose Open Folder.

Select Process Subfolders to decrypt messages in the selected folder and its subfolders, and then choose OK.

To encrypt messages in a folder

In the Exchange\<operating system\platform>\Security\Sectool directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, double-click Sectool.exe.

From the Exchange Security menu, choose Secure Folder.

Type your security password, and then choose OK.

Select the message store containing the messages you want to encrypt, and then choose OK.

Select the folder containing the messages you want to encrypt, and then choose Start Here. To select a subfolder, choose Open Folder. If you are moving messages between sites or recipient containers, select the folder containing the messages you decrypted before the messages were moved.

Select the options that you want to use for encrypting messages, and then choose OK.

Option | Description
Resecure previous secure messages | Encrypts only messages that were previously decrypted by this tool.
Encrypt all messages in folder | Encrypts all messages in the folder that were not previously encrypted.
Encrypt signed messages | Encrypts messages that are secured with digital signatures. If selected, digitally signed messages will be encrypted but no longer signed.
Process subfolders | Encrypts all messages that were not previously encrypted in the folder and its subfolders.


CleanSweep Tool

The CleanSweep tool enables you to specify which forms, views, or rules reply templates should be deleted. However, note that this level of control does not extend to rules and permissions. When you delete the rules and/or permissions associated with a folder, all rules and/or permissions for the folder are deleted.


Installing CleanSweep

To install the CleanSweep tool

  • From the Exchange\<operating system\platform>\Admin\Cleanswp subdirectory of the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Clnswp32.dll to your system directory (c:\Windows\System32 on Windows NT).


Using CleanSweep

To run the CleanSweep tool

At the command prompt, type RegEdit.

Beneath the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Exchange\
Client\Extensions registry key, add the following key value: Clnswp.

Note that the value for this key value should be: 4.0;c:\windows\system32\
clnswp32.dll;2 if you copied Clnswp32.dll to the proper directory (c:\Windows\System32) when installing the tool.

To delete rules, permissions, forms, views, or rules reply templates

In the Microsoft Exchange Client Viewer, select the folder or message store object that contains the items you want to delete.

From the Tools menu, choose CleanSweep.

Select the items you want to delete, and then choose OK.


Crystal Reports

Crystal Reports enables Microsoft Exchange users to create, view, and distribute presentation-quality reports that contain Microsoft Exchange-specific data. Such data can include information from the Microsoft Exchange Client, and the Microsoft Exchange Server.

Crystal Reports can use the following Microsoft Exchange data to create reports:

  • Message tracking logs that include the sender's name, date, message size, server, and so on.
  • Address Books that include a recipient's name, address, company name, phone, and so on. These address books can be personal address books (PABs), global address lists (GALs), or distribution lists (DLs).
  • E-mail messages, form applications, and properties of OLE Documents. This information appears in the folder contents list in the right pane of the Microsoft Exchange Client.

Each data source is treated as a database table, which enables you to combine data from different data sources. For example, you can combine the Message Tracking Log with an Address Book by using an e-mail address. You can also create a single report that contains historical data on all sent e-mail and sender information.

After the information is retrieved, Crystal Reports provides a rich set of summary functions and graphics to help you create a high-quality presentation.


Installing Crystal Reports

Crystal Reports enables the Microsoft Exchange Client to use selected core components to present large amounts of data in a sophisticated format.

To install Crystal Reports

  • From the Exchange\<operating system\platform>\Admin\Crystal subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all files to your computer.


Crystal Reports Overview

Crystal Reports for Microsoft Exchange contains core components that have been modified for the specific needs of Microsoft Exchange users. You can access these components through the Microsoft Exchange Client. The components include:

  • A 32-bit Microsoft Exchange client extension dynamic-link library (DLL) for Windows NT and Windows 95
  • A 16-bit client extension for Windows for Workgroups.

The following table lists the core Crystal Reports components available in the Microsoft Exchange Client.

Component | Description
Crystal extension for the Microsoft Exchange Client | Enables Microsoft Exchange users to access the Crystal Reports components necessary to design and analyze a report from within the Microsoft Exchange Client.
Microsoft Exchange Reports | Provides users with a set of predefined reports that can be used out of the box or as a starting point for further customization. The reports are installed in a samples directory. They are also included in a sample personal folder file (.PST) that contains both folder reports (templates) and report instances (templates and data).
Crystal Reports Viewer | Provides Microsoft Exchange users with the functionality to analyze, print, and export existing reports. The Viewer is a separate application that can be launched from within the Microsoft Exchange Client.
Crystal Reports Designer | Enables Microsoft Exchange users to create and modify reports by selecting data from a list of properties.

Crystal Reports adds menus, a property page, and toolbar buttons to the Microsoft Exchange Client.

Report Formats

Crystal Reports for Microsoft Exchange incorporates two types of reports: Report Templates and Report Instances.

Report Templates
  • A Report Template is not mapped to a physical file. It exists as a hidden message within a folder and is only accessible from within the Microsoft Exchange Client. To access a Report Template, you must choose a menu command.
  • A Report Template is similar to a Microsoft Exchange folder contents list view in that you can only see data from a single folder. The Report Template cannot display information from multiple folders.
  • Because data within a Microsoft Exchange folder is constantly updated, a Report Template does not contain saved data. It is associated with data contained in a public folder.
  • A Report Template may be either a Personal Report or a Folder Report. A Personal Report, similar to a Microsoft Exchange view, can be applied to any folder. A Folder Report, however, is associated with one specific folder.
  • You can access a Report Template by using the folder's property page or by choosing a command from the View menu. However, Report Template management (that is, creation, deletion, or modification) can only be accomplished by selecting options in the folder's property page.
  • A Report Template can only be applied from the View menu.
Report Instances
  • A Report Instance is a file with an .rpt extension. The file can reside within a Microsoft Exchange folder or elsewhere on your computer.
  • As with a Microsoft Word document, you can copy a Report Instance to a Microsoft Exchange folder by using drag-and-drop operations. You can also copy a Report Instance to a folder by using the Export function in either Crystal Reports Designer or Crystal Reports Viewer.
  • A Report Instance can be saved with or without data.
  • A Report Instance with current data contains a snapshot of data for comparison or storage purposes. This provides a way for an administrator to archive mail.


Using Crystal Reports

When you use Crystal Reports, you can save your report in a variety of file formats, including .rpt, .doc, .xls, .rtf, .and .txt. You can also choose to save the report in a variety of locations, including a Microsoft Exchange folder, as an attachment in e-mail, or as a separate file.

To start Crystal Reports

In the Microsoft Exchange Client Viewer, choose the View menu.

Select a report option.

Report Types

The following table lists the reports available in Crystal Reports:

Option | Description
Personal Reports | Displays the currently defined Personal Reports templates that are applicable to any folder as submenu items. By selecting a specific Report template, you start the Crystal Reports Analyzer for the selected Report template.
Folder Reports | Displays the currently defined Folder Reports templates that are defined for this folder as submenu items. By selecting a specific Report template, you start the Crystal Reports Analyzer with the selected Report template.
Define Reports | Displays the folder's property page for Views, Report Templates, and Forms for the currently selected folder.

Revised Microsoft Exchange Reports

The following table lists revised reports that are based on Crystal Reports for Microsoft Exchange. They have been renamed and modified to address specific needs:

Report Name

Description

Location

Mailbox_a.rpt

Mailbox Acount Information

Original functionality

Groups Microsoft Exchange mailboxes by Home Server, then Storage Limit Information. Shows Max Incoming and Outcoming Message Sizes, as well as the Total Message Size.

Revised and Additional Functionality

Based on the Crystal Reports for Microsoft Exchange Mailbox.rpt. This revised report corrects an error in the unit of the mailbox sizes. It can run once against many servers, and it shows the results from specific servers.

Microsoft Exchange Administrator program

Mailbox_d.rpt

Mailbox Acount Information

Original Functionality

Groups Microsoft Exchange mailboxes by Home Server, then Storage Limit Information. Shows Max Incoming and Outcoming Message Sizes, as well as Total Message Size.

Revised and Additional Functionality

Adds a Site Names field, and then adds another summary level grouped by site.

Microsoft Exchange Administrator program

Public_c.rpt

Public Folder Summary Report

Original Functionality

Lists the public folders on a server, including a list of the Microsoft Exchange Server computers on which it has been replicated. Includes the last access time for administrators to determine which public folders may be obsolete. Sorted in descending order by Total Message Size.

Revised and Additional Functionality

Lists the public folder replica summary. This report runs against a specific server. The report adds a field Newest Message Creation Time, not found in Public.rpt. Public.rpt hides the Detail section. Detail information can still be accessed by double-clicking the Summary line.

Microsoft Exchange Administrator program

Public_e.rpt

Public Folder Summary Report

Original Functionality

Lists the public folders on a server, including a list of the Microsoft Exchange Server computers on which it has been replicated. Includes the last access time for administrators to determine which public folders may be obsolete. Sorted in descending order by Total Message Size.

Revised and Additional Functionality

Enables users to select a folder to report on. When prompted for a folder name, users should type two backslashes followed by either the folder name, the first few characters of the folder name, or some portion of the folder name in conjunction with special characters, as shown in this example:

\\EFORM*

Notes

The folder name is case-sensitive.

The asterisk (*) stands for any character string.

The question mark (?) stands for any single character.

Microsoft Exchange Administrator program

Crystal Reports Viewer for Microsoft Exchange

The Crystal Reports Viewer opens each time you choose a Folder Report, Personal Report, or Folder Instance file from the Microsoft Exchange Client View menu. The Viewer enables you to view an existing Report Template or Report Instance in a variety of ways without changing its design. While working in the Crystal Reports Viewer, you can export the report to a Microsoft Exchange folder or disk, send it as an attachment, drill down for more details, modify the selection formula, and perform searches.

The Viewer is activated as a result of file association of *.rpt to the cvwxx.exe program. This enables you to start the analyzer for a selected report by double-clicking that report. If you choose several reports from the View menu, the Viewer displays multiple windows, one for each report.

Below is an example of the Crystal Reports Viewer with a sample Helpdesk report. While working in the Viewer, you drill down to view details on specific elements of this report.

In addition to the destination types already provided (disk file, MAPI user, VIM user), a Microsoft Exchange folder is also available as a report destination. When the report is run with its destination set as a Microsoft Exchange folder, the completed report appears as a new item in the indicated folder. This can be any folder you have access to, including a public folder on a Microsoft Exchange Server computer.

To view an existing Crystal Report

  • In the Microsoft Exchange Client Viewer, double-click a report in a folder; or select the report and press enter.

To view report properties

In the Microsoft Exchange Client Viewer, from the Public Folders menu, choose All Public Folders.

Select a public folder, and then right-click on the folder.

From the shortcut menu, select Reports.

You can view properties and options in the following tabs: General, Views, Design Overview, Forms, and Reports. Note that the Reports property page has the same look and feel as the View property page. When a folder design is copied to another folder, its associated views and reports are copied as well.

The Reports property page displays options for either the current Folder Reports for the selected folder or the Personal Reports that have been defined by the user. When a report is highlighted, the report title and description appear in the lower pane.

The following table lists options in the Report property page:

Option | Description
New | Opens the New Report dialog box. In this dialog box, you can select a Report Template name that will be used as a submenu label in the Microsoft Exchange Client. You can use an existing report or start the Crystal Reports Designer with the current Microsoft Exchange view. Then you can save the Report Template within Microsoft Exchange as a folder or a personal report.
Modify | Displays the Modify Report dialog box, which lists the name, title of a current report, and any related comments.
Delete | Deletes the Report Template from the folder.
View | Displays the selected report in the Crystal Reports Viewer.

To create a new report

In the Microsoft Exchange Client Viewer, select a public folder, and then right-click on the folder.

From the shortcut menu, select Reports, and then select New.

Ready-to-Use Reports for Microsoft Exchange

Crystal Reports for Microsoft Exchange includes a set of ready-to-use reports that meet the needs of both administrators and clients. You can also customize these reports.

The sample reports are located in the Crystal.pst file.

The reports fall into two categories: Report Instances and Report Templates. Report Instances are organized into the following folders: Message Tracking Logs, Microsoft Exchange Folders/Address Books, and Microsoft Exchange Administrator. The Help desk folder contains three Folder Reports. All other reports can be created by using the Crystal Reports software provided in this compact disc.

The following table lists the descriptions and locations of the sample reports available in this compact disc:

Report Name | Description | Location
detlrec.rpt Server Detail Report for Received Messages | Reports on local, gateway, and other Microsoft Exchange Server incoming message traffic. Groups data by the site name of message receiver. You can drill down each site for container information on each sender, and message-level information. Statistics include: average bytes per message, total number of messages, and total bytes. | Message Tracking Logs
detlsend.rpt Server Detail Report for Sent Messages | Reports on local, gateway, and other Microsoft Exchange Server outgoing message traffic. Groups data by the site name of the message sender. You can drill down each site for container information on each sender, site information for each sender, and message-level information. Statistics include: average bytes per message, total number of messages, and total bytes. | Message Tracking Logs
loadday.rpt Daily Message Traffic Report | Reports on daily message traffic for the week. Includes local and non-local message transmission. Statistics include: total messages, average message length, and largest message size. | Message Tracking Logs
loadhour.rpt Hourly Message Traffic Report | Reports on hourly message traffic for a day, including local and non-local transmission. Statistics include: total messages, average message length, and largest message size. | Message Tracking Logs
nodelivr.rpt Non-Delivery Report Summary | Lists non-delivery reports (NDRs) that were transmitted or received by a gateway, connector, or Microsoft Exchange Server. Report includes the destination site, e-mail address, and message-level detail. Statistics include: total number of messages and average byte size of message. Uses event #34 with Recipient Report Status =0. | Message Tracking Logs
servsum.rpt Server Summary | Reporting on incoming, outgoing, and local message traffic on Microsoft Exchange Server. Statistics include: total messages, average message size, average number of recipients, maximum number of recipients, and maximum message size. | Message Tracking Logs
srvin.rpt Server to Server Incoming Traffic Analysis | Reports on received messages that used connector, gateway, or other Microsoft Exchange Server computers. Report is grouped by messages received through a gateway or a Microsoft Exchange Server computer, site name of messaging service, and server name of message service location. The report graphs on site transmission and server transmission levels. Statistics include: total messages, total bytes per message, and average bytes per message. | Message Tracking Logs
srvout.rpt Server to Server Outgoing Traffic Analysis | Connector, gateway, or other Microsoft Exchange Server computers. Report is grouped by messages sent through gateway or a Microsoft Exchange Server computer, site name of messaging service, and server name of message service location. The report graphs on the site transmission and server transmission levels. Statistics include: total messages, total bytes per message, and average bytes per message. | Message Tracking Logs
topnrec.rpt Top Five Message Receivers Report | Report lists the top five message receivers for the log days, including local delivery and non-local delivery. You can drill down to view further details on each receiver. Information for each group includes total messages, average message size, and largest message. | Message Tracking Logs
topnsend.rpt Top Five Message Senders Report | Report lists the top five message senders for the log days, including local delivery and non-local delivery. You can drill to view further details on each receiver. Information for each group includes total messages, average message size, and largest message. | Message Tracking Logs
gal.rpt Global Address List | Lists all members in the GAL grouped by department. Includes department, display name, title, phone number, and e-mail address. | Folders/ Address Books
pab.rpt Personal Address Book | Lists all members in a PAB alphabetically and displays organizational information such as name, address, phone, and department. | Folders/ Address Books
inbox.rpt Inbox Archival Report | Extracts messages from an inbox for archiving to a disk. | Folders/ Address Books
mailbox.rpt Mailbox Account Information | Groups Microsoft Exchange mailboxes by home server, then storage limit information. Statistics include maximum incoming and outgoing message size, and total message size. | Microsoft Exchange Administrator program
public.rpt Public Folder Summary Report | Lists the public folders on a Microsoft Exchange Server computer, including a list of the Microsoft Exchange Server computers to which they have been replicated. Statistics include the last access time for administrators to determine which public folders may be obsolete. Sorted in descending order by total message size. | Microsoft Exchange Administrator program
ntevent.rpt NT Exchange Application Log by Date and Type | Reports on Windows NT events generated by Microsoft Exchange. Events are grouped by event type and date. | Microsoft Exchange Administrator program
Helpdesk Requests By Assigned To | Listing of Help desk requests grouped by Assigned To and sorted by Status. | Helpdesk Folder Report
Helpdesk Requests By Status | Listing of Help desk requests grouped by Status and sorted by Assigned To. | Helpdesk Folder Report
Helpdesk Requests By Subject | Listing of Help desk requests grouped by Subject and sorted by number of requests in descending order. | Helpdesk Folder Report

Using the Crystal Reports Designer for Microsoft Exchange

You can also use the Crystal Reports Designer to create or modify reports. The Designer provides a list of Microsoft Exchange columns that you can choose from. After you choose a column, you can drag and drop it into a report. You can then customize your report by adding text and formatting the data, fields, formulas, and summary operations.

To start the Crystal Reports Designer

In the Microsoft Exchange Client Viewer, select a public folder, and then right-click on the folder.

From the shortcut menu, choose Reports, choose New, and then select Crystal Reports Designer.

Specifying a data source

You can use the Crystal Reports Designer to create a Microsoft Exchange-specific report by choosing Microsoft Exchange Data as the data source for a new report. If you are accessing a folder or the Address Book, you must select a MAPI profile for logon.

The following three data sources are provided to the Microsoft Exchange user.

  • Microsoft Exchange folder
  • Address Books
  • Message Tracking Logs

In addition to the destination types already provided (disk file, MAPI user, VIM user), a Microsoft Exchange folder is also available as a report destination. When you run the report with the destination set as a Microsoft Exchange folder, the report appears as a new item in the selected folder.

Microsoft Exchange Server Administrator Reports

Crystal Reports provides the functionality to create reports for two types of Microsoft Exchange Administrator objects: Microsoft Exchange public folder properties and mailboxes on the server. However, this functionality is not included with this compact disc. To view these objects, you must be running Crystal Reports from a Microsoft Exchange Server computer.

Microsoft Exchange public folder properties

Crystal Reports enables you to specify which information you have permissions to, where the public folder is replicated, and the storage limits.

The reporting properties are:

  • Access Control Lists (ACLs)
  • Age Limit for Replicas
  • Folder Name
  • Folder Path Name
  • Issue Warning Storage Limit (K)
  • Last Access Time
  • Newest Message Creation Time
  • Number of Messages
  • Oldest Message Creation Time
  • Replica List
  • Storage Quota (K)
  • Total Message Size (Byte)
  • Use Default Storage Limit
Microsoft Exchange mailbox properties

You can also report mailbox information on the server, permissions, which server is used, and message size limits.

Following is the list of mailbox properties:

  • Home Server
  • Issue Warning Storage Limit (K)
  • Last Logoff Time
  • Last Logon Time
  • Mailbox Name
  • Max Incoming Message Size (K)
  • Max Outgoing Message Size (K)
  • Permissions
  • Primary Windows NT Account
  • Prohibit Send Storage Limit (K)
  • Storage Limit Information
  • Total Message Size (Bytes)
  • Use Default Storage Limit


DL Import Tool

The Microsoft Exchange Distribution List (DL Import) tool provides a single, standardized, and time-effective process for creating distribution lists by extracting information from other previously created lists. These lists may have been created with a Microsoft Access database, a Microsoft Excel macro, or another application.

DL Import eliminates the inefficiency of having data stored in numerous formats, created in numerous ways, and residing on different servers. This tool also automates the process of updating distribution lists on a regularly scheduled basis.


Installing DL Import

To install the DLImport Tool

  • From the Exchange\<operating system\platform>\Admin\DLImport directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all the files to your computer.
  • At the command prompt, type: DLImport -fi

Installing and Running the Metrics Service

The DLImport -fi command instructs the Metrics service to install itself as a service on the system and set the account value to what you specify in the command. Running this command forces the new registry defaults into the local registry.

To start the Metrics service

  • At the command prompt, type:

    Metrics -fi \u<domain>\<user_name>\p<user_password>


Using DL Import

DL Import uses the Crystal Reports tool to create the raw data required to generate the distribution lists for buildings, groups, and servers. The server reports are scheduled to run on a daily basis against the Mailbox Administrator to obtain server data. The building and group reports are scheduled to run on a weekly basis against the global address list (GAL).

Some of the data is derived from cross-tabulated tables. Crystal Reports uses cross-tabulated tables to obtain distribution list (DL) aliases and long e-mail addresses.

The scheduled reports are formatted as a .csv file that is sent to a share point. If Crystal Reports fails to create the required data, an automatic e-mail notification is sent to the users defined in the requirements list.

The Windows NT process monitors the share point for a new file. When a new file is detected, it renames the old file and processes the new file. The process parses the .csv file to create the distribution lists. When it has created the distribution lists, it replaces the distribution lists in Microsoft Exchange Server using the designated e-mail address. If a distribution list is not created, the Windows NT process sends an automatic mail notification to the users defined in the requirements list.

Generating Data with Crystal Reports

The first report generated by Crystal Reports contains a list of all mailboxes sorted by the home server distribution list name. This report runs off the Mailbox Administrator table. A user with a site Microsoft Exchange Administrator account can run this report against all servers within that site.

To generate the report

Use the server name to link to the server cross-tabulated table and return the distribution list names and e-mail addresses described in the table below. The result of the server report is exported to a .csv file that is sent to a file share. The server .csv file contains the following attributes: SDL E-mail Address, SDL Alias Name, Recipient E-mail Address, and Recipient Alias Name.

The following table lists the definitions for these field names and data sources:

Field Name | Description
SDL E-mail Address | The distinct e-mail address of the server distribution list (SDL). The data file is sorted on this field and is obtained from the server cross-tabulated table.
SDL Alias Name | The e-mail alias of the server distribution list that is obtained from the server cross-tabulated table. This field is included in the .csv file for maintenance and troubleshooting purposes only.
Recipient E-mail Address | The distinct e-mail address of the mailbox on the specified server.
Recipient Alias Name | The e-mail alias of the mailbox recipient on the specified server that is obtained from the Account field in the personal address book (PAB) table. This field is included in the .csv file for maintenance and troubleshooting purposes only.

Develop a Crystal Report that runs against the global address list (GAL)and contains a list of all mailboxes sorted by the building's distribution list name (DL_Dist_Name). This report is used to generate the raw data for the building and group distribution lists. The groups are defined in the building cross-tabulated table.

Crystal Reports extracts the building numbers by using a specific formula. After the building numbers are extracted, they will be used to link to the building cross-tabulated table and return distribution list names and e-mail addresses as described in the following step.

The result of the building report is exported to a .csv file and sent to a file share. The building .csv file will contain the following attributes: BDL E-mail Address, BDL E-mail Alias Name, GDL E-mail Address, GDL E-mail Alias Name, Recipient E-mail Address, and Recipient E-mail Alias Name.

The following table lists the definitions for these field names and data sources:

Field Name | Description
BDL E-mail Address | The distinct e-mail address of the building distribution list (BDL). The data file is sorted on this field. Obtained from the building cross-tabulated table.
BDL E-mail Alias Name | The e-mail alias of the building distribution list. Obtained from the building cross-tabulated table. This field is included in the .csv file for maintenance and troubleshooting purposes only.
GDL E-mail Address | The distinct e-mail address of the group distribution list. Obtained from the building cross-tabulated table.
GDL Alias Name | The e-mail alias of the group distribution list. Obtained from the building cross-tabulated table. This field is included in the .csv file for maintenance and troubleshooting purposes only.
Recipient E-mail Address | The distinct e-mail address of the mailbox recipient in the specified building.
Recipient E-mail Alias Name | The e-mail alias of the mailbox recipient in the specified building. Obtained from the Account field in the PAB table. This field is included in the .csv file for maintenance and troubleshooting purposes only.

Searching Cross-Tabulated Tables

Crystal Reports needs to attach to a Microsoft Access cross-tabulated table. The Crystal Reports tool then uses either the server name or the building number to search the cross-tabulated tables and return the alias name and e-mail address of the distribution lists.

The following table lists field name descriptions for both the Building and Server cross-tabulated tables:

Field Name | Description
Building Number | The building number is used to search the table to retrieve Microsoft Exchange alias names and e-mail addresses for building and group distribution lists. The table must include all building name variations (for example, <201N>). Although the building names can be a combination of letters and numbers, they cannot consist of all letters and no numbers. For example, building names such as "Test" or "Mobile" are not valid.
BDL E-mail Address | The distinct e-mail address of the building distribution list.
BDL E-mail Name | The e-mail alias name of the building distribution list.
GDL E-mail Address | The distinct e-mail address of the group distribution list.
GDL E-mail Name | The e-mail alias name of the group distribution list.

The naming conventions for the building distribution list names are contained in the server name and location table. Following are the field name descriptions for the server name and location table:

Field Name | Description
Site\Server | The name of the server site and home server. This information is used to retrieve Microsoft Exchange alias names and e-mail addresses for server distribution lists.
Server Name | The name of the home server. This information is used to build the Site/Server field.
SDL E-mail Address | The distinct e-mail address of the server distribution list name.
SDL E-mail Name | The e-mail alias of the server distribution list.
Server Site | The site of the specified server. This information is used to build the Site/Server field.

Monitoring the Share Point and Creating New Distribution Lists

The Windows NT service process monitors a share point for a new file to be sent by Crystal Reports. The file names for the .csv files are Svrlist.csv and Bldlist.csv.

When a new file is detected, the Windows NT process creates a backup copy of the old file, and then parses the .csv file to create the distribution lists. The backup file names are: Svr<yy/mm/dd>.csv and Bld<yy/mm/dd>.csv.

When the distribution list's e-mail address changes, the Windows NT process performs processing breaks. This event initiates the creation of a new distribution list.

The Windows NT process must create two different distribution lists from the building .csv file: the building distribution list and the group distribution list. If a row in the file has a null group, then it is not included in the group distribution list because the recipient is not an employee.

Note The Windows NT process needs to be designed so that it knows where it left off if it is interrupted while processing distribution lists, so that it can automatically continue processing where it left off. This type of situation might occur during a server reboot.

After the distribution lists are created, the Windows NT process replaces the distribution lists in Microsoft Exchange and retains the permissions of the original distribution list. Windows NT security is used so that only input from the account running Crystal Reports is accepted.

If a distribution list is not created, the process sends an automatic notification to the users defined in the requirements list, identifies which distribution lists did not get created, and explains why (if the cause is known).

Windows NT Registry Data

DL Import uses Windows NT registry data located in the following hierarchy: \HKEY_LOCAL_MACHINE\SOFTWARE\MSITG\CONSTOOLS\DLIMPORT\

The DL Import tool monitors for an event that indicates that a registry change has been made. The service parameters known at this time are listed below:

Registry Key | Description | Registry Value Type | Default
DLImport_Polling _Frequency | How often the service inspects the CSV_File_Location for any .csv file to process. | Registry Value Type: REG_DWORD | 1 minute
CSV_File_Location | The absolute path where the .csv file will be stored by Crystal Reports on its server. | REG_SZ | \\na-01-rpt\dlimport
CSV_Data_Files | The csv file name if the file is located at CSV_File_Location. Else, a UNC name is supported. | REG_SZ | "bldglistCSV, empgroupCSV"
CSV_Archive_ Location | The absolute path where the .csv files are archived on the DL Import server. | REG_SZ | The CSV_File_ Location and a subdirectory called Archive. (example: \\na-01-rpt\dlimport\ archive).
Notification_Alias | The list of aliases that DL Import sends notification to when a DL processing error occurs. | REG_MULTISZ | <approved e-mail alias names>
EventLog_Level | The logging level used by the service when writing to the EventLog. | REG_DWORD | 5 (debug)
LogFile_Level | The logging level used by the service when writing to the log file. | REG_DWORD | 5 (debug)
Exchange_Logon _Profile | The profile used to connect to the GAL by the DL Import tool. | REG_SZ | "dlimport"

Windows NT Registry Logging Functions

Settings within the Windows NT registry are used to control the level of logging to the log file and the Windows NT EventLog. In other words, the degree of detail contained in the logs can be modified. Predetermined settings are used to control these logs. Documentation on the settings and their necessary location within the registry is provided with the tool

The debug log file for this tool should be named "DLimport.log" and created in the Binaries directory (or a Logs subdirectory).

The debug log file should contain only debug and processing status information. All other information used for an audit trail should be written to the application EventLog.


Duplicate Proxy Tool

The Duplicate Proxy tool enables you to search for directory entries that contain duplicate proxy addresses. In most cases, duplicate proxies are prevented from being created, but in scenarios where replication occurs, duplicate proxy entries can be created in different sites.


Installing the Duplicate Proxy Tool

To install the Duplicate Proxy tool

  • From the Exchange\<operating system\platform>\Admin\Psearch directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Dupproxy.exe and Wldap32.dll to your computer.


Using the Duplicate Proxy Tool

To use the command-line Duplicate Proxy tool, you must have lightweight directory access protocol (LDAP) configured on your computer. The tool searches for specific variables depending how your query is structured.

To search the Microsoft Exchange Server directory for entries with duplicate proxy addresses

At the command prompt, switch to the directory where Dupproxy.exe is installed.

Type dupproxy with one of the following variable options.

The correct syntax is: Dupproxy <Microsoft Exchange Server computer name> <proxy type> <proxy value>

Option | Description
<Microsoft Exchange Server computer name> | The name of the Microsoft Exchange 5.0 Server computer with LDAP configured, where you want to run the query.
<proxy type> | The e-mail address type of the proxy you are searching for [for example, simple mail transport protocol (SMTP) or X.400].
<proxy value> | The value you are searching for (for example, username@microsoft.com).

You can also search for any object with a proxy of type SMTP with the prefix characters of the user's alias. For example, to perform a search of this type, you can use the following syntax: Dupproxy exchange1 SMTP username*.


EFD Handcode Agent

The EFD Handcode Agent enables you to paste or copy your handcode text when adding it to your EFD project script file. By using simple scripting commands, you can play the script, and your handcode is automatically inserted into your EFD project source-code files.

You can also customize your EFD project with Microsoft Visual Basic® code and then return to EFD as needed. When you return to EFD, the EFD changes are merged with your Visual Basic hand-coded changes automatically.


Installing the EFD Handcode Agent

To install the EFD Handcode Agent

From the Exchange\<operating system\platform>\Developr\EFDhandc subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Efdcoder.exe to your computer.

From the Start menu, choose Run, and then choose Browse to search for the folder or subdirectory where you copied the file.

Select the EFD handcode folder, and then select Setup.exe.

When you run Setup.exe, the Visual Basic 4.0 32-bit run times are automatically loaded.


Using the EFD Handcode Agent

The EFD Handcode Agent program includes a sample project file (listdemo.efp) that demonstrates how to use handcode to link two list boxes together. This sample file is located in the Listdemo folder.

You can also find EFD-generated source-code files and three additional files in the Listdemo\Vb subfolder.

Warning Do not delete the following files: Handcode.ini, Handcode.bas, and Handcode.rtf.

Handcode.ini contains the list box data.

Handcode.bas contains global variables and subroutines for populating the list boxes from the Handcode.ini file.

Handcode.rtf is the script file that Efdcoder uses to reinsert the necessary handcode into the EFD source files.

To install the Efdcoder form

From the Start menu, choose Run, and then select Browse to search for the directory where you stored the Efdcoder.exe file.

Double-click Efdcoder.exe.

This step starts the Efdcoder script.

Choose Open to open the File Open dialog box.

In the Listdemo\Vb subfolder, select Handcode.rtf.

Choose Run, and then choose Compile.

Your modified sources are recompiled by Microsoft Visual Basic and then converted to an .exe file.

Choose Install to install the form on your Microsoft Exchange Client.

Tips for Using the Efdcoder Form

Following are tips to help you use the Efdcoder form effectively:

  • To single-step through your script file, choose the Step button instead of the Run button.
  • To open a shortcut menu, right-click the top portion of the handcode menu.
    • If nothing is currently selected , a list of verbs appears. Select a verb to insert it into your handcode file at the current insertion point.
    • If you have selected text, then a text format menu appears.
  • To insert previously selected text, choose the Insert button between the two windows.
  • To maximize the handcode window so that it fills the entire screen, choose the Zoom button. This feature is useful when you are building a script file because you can paste or copy source code while working in Visual Basic.


Event Log Tools

You can use the Event Log tools to:

  • Monitor events on more than one server.
  • Filter events based on service, type, and ID.
  • Alert a computer or user through e-mail when specified events occur.
  • Restart or stop a service


Installing the Event Log Tools

To install the event log tools

  • From the Exchange\<operating system\platform>\EventLog directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the files into a directory on a computer that is running the services you want to monitor.

    Note To have Event Scan alert you through e-mail, you must install it on a computer that has MAPI installed (for example, a Microsoft Exchange Server computer or a Microsoft Exchange Client computer).


Specifying Servers and Events to Monitor

Use the Event Log Filter tool (Elf.exe) to specify the servers and events that you want to monitor. After you specify what you want to monitor, the tool writes the results to a text file. For the message IDs, make sure to point the Event Log Filter installed on version 5.0 to 5.0 servers and point Event Log Filters installed on 4.0 to 4.0 servers. You can then monitor events on servers, or filter events saved in .evt files by using the Windows NT Server Event Viewer.

Note You can save an event log filter by using the Configuration Add and Remove buttons.

To specify the servers and events you want to monitor

Run Elf.exe.

Choose Add and Remove to specify the servers and .evt files you want to monitor.

Specify the name of the output text file.

Specify how far back you want to check events.

Select the services you want to monitor.

Choose Advanced to specify individual event IDs to ignore for a service.

Specify the entry types you want to monitor.

Select the Unattended box if you want to skip over errors and continue.

Choose Go to start the filter.

The output text file created is in the same format as the Windows NT Server Event Viewer, except that it monitors more than one server and it adds the text description for events.

Displaying Event Log Output in Microsoft Access

If you have Microsoft Access installed, you can use the Microsoft Access Elf.mdb file to provide common summaries of the events.

To have Microsoft Access Elf.mdb display event summaries

Start Microsoft Access.

Open Elf.mdb.

Choose Open Event Log and specify the full path to the output file created with the Event Log Filter.

Choose View Details.

The top half of the view window shows the count of each event ID found. Click an event to see individual occurrences in the bottom half of the window.Note that the Elf.mdb database will grow with use. You need to compact this database manually by using the Tools.Database Utilities.Compact Database option in Microsoft Access.


Monitoring for Specific Events

You can use the Event Log Scan tool (Evtscan.exe) to monitor servers for specific events. When a specified event is detected, the Event Log Scan tool can be configured to:

  • Start an application or specify any other command-line directives.
  • Send a message by using a selected profile and password.
  • Send a network pop-up message to specific computers.
  • Restart or stop the service.

To run the Event Log Scan tool

Create a configuration file with a .cfg extension specifying the events and actions required. The format is as follows:

EventID;Source;Action;Alert list;Mail list;Command line;Comment string;

Following is a list of each configuration entry and a description for the type of event.

Configuration Entry | Description
Event ID | The numerical event ID (see the Windows NT Event Viewer).
Source | The source name for the service to monitor.
Action | The action to take; can be Restart or Stop.
Alert list | A comma-separated list of computers to send network pop-up messages to when the event is detected.
Mail list | A comma-separated list of e-mail aliases to notify when the event is detected.
Command line | Command line with parameters (can be up to 256 characters in length).
Comment string | A comment that is included in the alert pop-up message and e-mail message when the event occurs.

Run Evtscan.exe by using the following command-line format:

Evtscan -f <config_file> -u <profile_name> [-p <password>]
[-t <delay_in_seconds>] server_list

where config_file is the name of the configuration file created in step 1, delay_in_seconds is the time the tool waits between scans (for example, typing -t 15 sets the tool to scan for events every 15 seconds), profile is the name of the exchange profile to be used, password is the password for the profile, and server_list is a comma-separated list of the servers to monitor for the events.

Following is an example of typical syntax usage for the Event Log Scan tool: Evtscan -f test.cfg -u scan -t 15 server1,server2,server3

Leave Evtscan running on your computer desktop. You may want to minimize the command prompt window.

Sample Configuration File

The following is a sample configuration file.

;sample config file.
;Event ID;Source;Action;Alert List;Mail List;Command;Comment String
9277;MSExchangeMTA;restart; monitorwks1; johncole;winbeep.exe;Event 9277
9278;MSExchangeMTA;stop; monitorwks1;;notify.bat;Event 9278
9279;MSExchangeMTA;; monitorwks1; Aron Mecsi;;Event 9279
9299;MSExchangeMTA;;monitorwks1,monitorwks2;ChbierZ,EtueD;;Shutdown Complete


Global Send Options Tool

The Global Send Options (GSO) tool is managed by a dynamic-link library (Gso.dll). This tool enables users to set the deferred send time and encoding type for Internet attachments on a global basis rather than on a per-message basis when composing new messages in the Microsoft Exchange Client. This tool is designed to work with Microsoft Exchange Server.


Installing GSO

Upon installation, the Gsoinst.exe file creates the appropriate registry entry in the list of Microsoft Exchange Client extensions.

To install the GSO tool

From the Exchange\<operating system\platform>\Client\GloblSnd subdirectory on the Microsoft BackOffice Resource Kit, Part II, compact disc, copy Gso.dll and Gsoinst.exe to your computer.

At the command prompt, switch to the directory where you copied the files.

Type gsoinst <Gso.dll pathname>.

For example, if you copied the files to your C:\Exchange directory, switch to this directory and then type:

gsoinst c:\exchange\gso.dll

If you are running the Microsoft Exchange Client or Schedule+, quit these programs.

Start (or restart) the Microsoft Exchange Client to load Gso.dll.

To manually load Gso.dll rather than running Gsoinst.exe

Create a new string value under: HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Client\Extensions and give it the value:

4.0;<path>;1;00000100000100;1000010;MSEMS

where <path> is the full path name to Gso.dll.


Using GSO

To change the Deferred Send/Internet Attachment encoding settings

In the Microsoft Exchange Client Viewer, from the Tools menu, select Options.

Select the Global Send tab.

You can now set the time for the Deferred Send option, as well as the type of encoding for attachments intended for the Internet.

Note If you select the Check for existing settings before putting global settings on message option, then Gso.dll will determine whether you have already set Deferred Send or Internet attachment encoding options for the message. If so, Gso.dll will not replace the old settings with the new global settings.


Internet Mail Service Sample Extension DLL

The Internet Mail Service Sample Extension dynamic-link library (Imcext.dll) intercepts inbound messages from simple mail transport protocol (SMTP) hosts and selectively reroutes those messages to other hosts before they are processed by the Internet Mail Service. This enables the Internet Mail Service to act as a smart host that can route messages between the Internet and other SMTP hosts.

For example, if your organization uses multiple SMTP hosts, this extension enables you to designate the Internet Mail Service as the single point of contact to the Internet. Other SMTP hosts can be configured to forward all messages to the Internet Mail Service, where the extension will route messages appropriately.

The sample DLL modifies envelope addresses. However, it doesn't modify any message headers or the message body.


Installing the Internet Mail Service Sample Extension DLL

To install the Internet Mail Service Sample Extension DLL

From the Exchange\Samples\IMCext directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Imcext.dll to a server running the Internet Mail Service.

Create a registry value named ExtensionDLL that points to Imcext.dll.

The key is HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet
\Services\MSExchangeIMC\Parameters. The type is REG_SZ. The value is c:\path\Imcext.dll, where path is the path to the sample extension DLL.

In the Imcdata directory on the Microsoft Exchange Server computer, create a configuration file named Imcroute.cfg.


Using the Internet Mail Service Sample Extension DLL

When initialized, the Internet Mail Service Sample Extension DLL loads a table named Imcroute.cfg from the configuration file you created. This file is in the directory specified in the RootDir Internet Mail Service registry value.

Comparing Domain Names

The Imcroute.cfg table contains a list of domain names and associated SMTP hosts. For each recipient of every inbound message the Internet Mail Service receives, the Internet Mail Service Sample Extension DLL must compare the domain name on the address to the list of domain names in the table. If a match is found, the message for that particular recipient is rerouted to the associated host.

The match is compared to the rightmost part of the domain name on the recipient address. For example, if the domain name in the table is sea.com, it matches an address of x.sea.com, as well as sea.com. The list is searched from top to bottom, and the first match is used. It is recommended that you list more specific patterns before general patterns to ensure that the names are found.

In cases where the associated SMTP host is localhost, domain names in the list represent names that should be handled by the Internet Mail Service. If the recipient address matches one of these domain names, the Internet Mail Service processes the recipient normally and attempts to deliver the message to the Microsoft Exchange Server. If no match is found, the Internet Mail Service Sample Extension DLL reroutes the outbound message to the domain name in the recipient's address. For this reason, it is important to ensure that any domain names that must be routed to the Microsoft Exchange Server computer are listed in the configuration file. In particular, any domain names used in SMTP addresses for Microsoft Exchange users must be defined in the configuration file. Otherwise, reports and replies will not be deliverable and could cause routing loops.

It is possible to introduce a message routing loop if the configuration file contains incorrect or incomplete information. It is recommended that you enable the DisableLoopbackConnections Internet Mail Service registry value to reduce the chance of a message routing loop occurring.

Configuration File Example

The following is an example of a configuration file.

! Internet Mail Service Extension DLL Configuration File

! Event log parameters

EL_EventLogging | ReRouted
EL_EventLogging | NotRouted
Listserv.granite.com | listserv.granite.com
granite.sea.com | localhost
sea.com | mail.sea.com
granite.com | localhost

Lines beginning with an exclamation point (!) or a blank line are comments and are ignored. The keyword EL_EventLogging controls whether events are recorded to the Windows NT Workstation Event Log for messages that are processed. EL_EventLogging must be followed with ReRouted or NotRouted. ReRouted indicates that an event is recorded whenever an outbound message is rerouted. NotRouted indicates that an event is recorded whenever a message is not rerouted.

Message Routing Example

Given the previous configuration file, the following are examples of message routing based on matching the domain name in the recipient's address:

Recipient | Routed to
user@listserv.granite.com | listserv.granite.com
user@granite.sea.com | localhost
user@sea.com | mail.sea.com
user@granite.com | localhost
user@pike.granite.com | localhost
user@anything.else.com | anything.else.com


Import Header Tool

The Import Header tool creates header text files for importing and exporting a variety of directory objects, such as mailboxes, dynamic-link libraries (DLLs), gateways, and details templates. The tool can also be used to load a header from an existing directory import or export file. You must run Import Header on a Microsoft Exchange Server computer, and the directory service must be running.


Installing Import Header

To install the Import Header tool

  • From the Exchange\<operating system/platform>\Migrate\Headers directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Header.exe to your computer.


Using Import Header

Use the following procedure to run Import Header.

To create a header file

In the Exchange\<operating system/platform>\Migrate\Headers directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, run Header.exe.

When the Import Header tool finishes loading the schema, select either Import or Export under Directory Mode.

Under Object Class, select the type of object you want to import or export.

Under Available Attributes, select the attributes to include in the header file. Attributes displayed in bold are required for the selected object; dimmed attributes cannot be imported. For more information about directory attributes, see the Microsoft Exchange Server Migration Guide.

Choose Add to add the attributes from Available Attributes to Selected Attributes. Choose Remove to remove attributes from Selected Attributes. Note that if you remove required object attributes when creating an import file, objects may not be imported.

Select File to specify a text file to use as the header file. If you select an existing import/export file, the file's existing header is loaded into the Selected Attributes column.

Select Generate to add the selected attributes to the header file. The header file is now ready to be used for directory import and export.

Note The Schema.hlp file provided in the Microsoft Exchange Server Software Developer's Kit describes all the attributes of the Microsoft Exchange directory service. Use this Help file with the Import Header Tool to determine which attributes to import or export.


Internet Idioms Tool

The Internet Idioms tool enables you to add text formatting flexibility to your Microsoft Exchange Client so that it behaves more like a traditional Internet mail client. With Internet Idioms, you can create automated signatures and prefixed replies, and change the default read font from Arial 10 to a font of your choice.


Installing Internet Idioms

To install the Internet Idioms tool

  • From the Exchange\<operating system\platform>\Client\Inetxidm subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Inetxidm.exe and Inetxidm.dll to your system directory (Windows\System on Microsoft Windows 95; \Windows\System32 on Windows NT).

    Note Before trying to run Internet Idioms, verify that you have Msvcrt40.dll in your system directory. You must have this dynamic-link library (DLL) to run Internet Idioms.


Using Internet Idioms

To run Internet Idioms, you must be running Microsoft Windows 95 or
Windows NT 4.0 with Microsoft Exchange Server and MAPI installed.

Note The Internet Idioms tool does not work with Microsoft Office 95 or 97 WordMail, because the WordMail forms don't support client extensibility. If you are using WordMail, you don't need the Internet Idioms tool because WordMail already contains most of the idioms included in this tool. In addition, this tool does not work with the simplified Send Note form included in the Microsoft Windows 95 Messaging Update. This prevents Internet Idioms from appending signatures to messages sent through Microsoft Internet Explorer, unless you do the following: From the Tools menu, choose Options, select the Send tab, and then clear the Use Simplified Send Note option.

If you read messages "on behalf of" another recipient using the Internet Mail Service component of Microsoft Exchange Server, Internet Idioms cannot change the read font.

To run the Internet Idioms tool

From the Start menu, choose Run.

Choose Browse to locate the directory where you copied Inetxdm.exe and its DLL.

Double-click Inetxdm.exe.

Changing a Default Font

You can specify the default read font by setting options in the Idioms tab. After you set the default font, any message that was not sent in rich text format appears in this font, rather than in Arial 10. The Courier 10 font is recommended because it is a monospace font and easy to read.

To change the default read font

In the Microsoft Exchange Client Viewer, choose Options from the Tools menu.

Select the Idioms tab.

Adding or Removing Boilerplate Message Text

Note Internet Idioms is only available in English. When used with a non-English-language version of Microsoft Exchange, it generates reply text that consists of a mixture of English and the localized language.

To add or remove boilerplate message text

In the Microsoft Exchange Client Viewer, choose Options from the Tools menu.

Select the Idioms tab, and then select the Text check box.

Creating a Signature Block in a Monospace Font

Non-rich-text recipients will view your signature block in monospace font.

To compose a signature block that looks good in a monospace font

Create your text in Notepad or another monospace editor

Paste the text into the Idioms signature box. Note that signature block size cannot exceed 4K.

Another check box enables you to type a reply prefix string. If you select this check box, Microsoft Exchange changes the format of your replies to prefix each line of text with this string.

Note that if the original message consisted of Microsoft Exchange-style paragraphs, this function will place quotation marks around the entire paragraph with only a single-prefix character. It does not break the paragraph into lines. If a long message is created, or one that contains Microsoft Exchange-style paragraph lines in its first few lines, Internet Idioms prompts you to use the native Microsoft Exchange reply format.

After you select a read font, this setting overrides any other font that you select.

To revert to the original send font

  • Press Ctrl+Space.


Removing Internet Idioms

To remove Internet Idioms

Quit Microsoft Exchange and log off.

At the command prompt, type Regedit.

Under the registry key: HKEY_LOCAL_MACHINE\Software\Microsoft \Exchange\Client\Extensions\CODE, delete the &quot;Internet Idioms&quot; tag and its value.

Delete the Inetxidm.dll from your system directory.


Mailbox Cleanup Agent

You can use the Mailbox Cleanup Agent to control client use of disk space on Microsoft Exchange Server computers. The Mailbox Cleanup Agent gives administrators the flexibility to delete and move outdated messages in users' mailboxes.

The Mailbox Cleanup Agent consists of a Windows NT Server service, a configuration object in the Microsoft Exchange Server directory, and a mailbox agent. Configuration information is contained in the Mailbox Cleanup Agent directory object in the Add Ins container. The mailbox agent originates the status reports that are sent to users after their mailbox has been cleaned. One instance of the Mailbox Cleanup Agent controls an entire site.


Installing the Mailbox Cleanup Agent

From the Exchange\<operating system\platform>\Security\Keytoken subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Keytoken.exe to your computer.

In the Tools\Cleanup directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, double-click Setup.exe.

Provide the following information:

  • The Microsoft Exchange Server computer where the Mailbox Cleanup Agent will reside. This can be any server in the site.
  • The site name.
  • The container where the Mailbox Cleanup Agent will be located. You can place it in any recipient container in the site (for example, the Recipients container).
  • The service account and service account password. This account is the security context the agent runs under. It can be any account, but it's a good idea to use the service account that you are using for the Microsoft Exchange Server services.
  • The service directory specifying where the Mailbox Cleanup Agent will be installed. The path to this directory must include a drive letter.

In the Microsoft Exchange Server Administrator program, find the Mailbox Cleanup Agent in the container you specified in the previous step and open its property pages. Configure the containers and schedule pages.

After Setup is completed, start the Mailbox Cleanup Agent service using Services in Control Panel.

Note If you start the service before configuring the agent's property pages, the service stops and logs an event indicating that it has not been configured.


Using the Mailbox Cleanup Agent

You can configure the Mailbox Cleanup Agent to move messages based on age limits. Within each recipient container in a site, age limits can be set on the user's Inbox, Sent Items folder, Deleted Items folder, and all other folders as a group. Outdated messages can be moved to the Deleted Items folder or to a special private folder so users can process the messages at their own discretion. After the Mailbox Cleanup Agent has cleaned out a mailbox, it sends a message to the user describing the cleanup operations that were performed. The tool also logs information for administrators to the Windows NT Server Event Log.

To enforce when deleted items are permanently deleted, the tool can be set to delete items from the Deleted Items folder. To allow your users to control which messages are deleted, you can configure the Mailbox Cleanup Agent to move messages to the System Cleanup folder. If the System Cleanup folder doesn't already exist when cleanup is run, the Mailbox Cleanup Agent creates it. The System Cleanup folder is a private folder in the user's mailbox that can remind users to delete outdated messages. It does not actually delete the messages; users can keep messages moved to the System Cleanup folder by dragging and dropping them into a personal folder file (.pst file).

The System Cleanup folder contains subfolders for each folder that is cleaned. For example, if you configure the Mailbox Cleanup Agent to move messages in Sue's mailbox to the System Cleanup folder, the folder hierarchy might look as follows:

Inbox

Sent Items

Sue's Folder

System Cleanup folder

Inbox

Sent Items

Sue's Folder

Setting General Configuration Options

In the Administrator window, choose Recipients.

Double-click the mailbox agent for the Mailbox Cleanup Agent.

Select the Containers tab.

In the left side of the Containers property page, select the container for the mailboxes you want to clean. The settings for the selected container are displayed on the right side of the property page.

Specify the age limits on folders and where outdated messages will be moved.

Option | Description
Use parent's configuration | The selected container is cleaned using the same settings as the parent container. This option is available on child containers only. It is enabled by default. When this option is selected, other options in the property page are disabled, except for Exclude mailboxes.
Folder | The folders containing the messages you want to move or delete. You can set age limits for messages in the Inbox, the Sent Items folder, and all other folders as a group.
Age limit (days) | The limit on how old messages can be before they are moved during the scheduled operation of the Mailbox Cleanup Agent.
Move to folder | Qualifying messages are moved to either the Deleted Items folder or the System Cleanup folder.
Permanently delete items in the Deleted Items folder older than (days) | The limit on how old messages in the Deleted Items folder can be before they are permanently deleted during the scheduled operation of the Mailbox Cleanup Agent. If an age limit is not specified, deletion depends on the user's default configuration. If a number of days is specified, messages are permanently deleted if their receive date is older than date the tool is run minus the specified number of days. If you want to postpone deletion of messages that are moved during the same session, set the age limit to a number greater than the age limit for the other folders.
Max number of items to move per mailbox | The number of messages that are moved before the Mailbox Cleanup Agent stops cleaning one mailbox and begins processing another. Deleted items are deleted only after those in all other folders have been processed. So, if the limit of items processed in other folders is reached before those in the Deleted Items folder are processed, then the items in the Deleted Items folder are not deleted. The default is 50.
Exclude mailboxes | Excludes specified mailboxes in the container from the cleanup session.

You can set up the Mailbox Cleanup Agent to run unattended on many mailboxes throughout a site according to the schedule you specify.

Setting the Cleanup Schedule

In the Administrator window, choose Recipients.

Double-click the mailbox agent for the Mailbox Cleanup Agent.

Select the Schedule tab.

Specify the cleanup frequency to daily, weekly, or monthly.


Mailbox Migration Tool

The purpose of the tool is to make a complete copy of the mailbox content from one server to another when these servers are in different sites and/or organizations. The utility does not assume there is direct network connectivity between any two servers and its basic mechanism is to create a personal folder file (.pst) which contains the structure and messages of the mailbox to be copied. In addition, this tool is used to recreate rules and directory information.

This tool augments the Exchange Administrators Move Mailbox option which only allows you to move a mailbox between servers within the same site. Using this utility, you can move mailboxes between sites.

This tool is useful for the following functions:

  • When a user or number of users move locations and need to have a mailbox in a different Microsoft Exchange Site. This utility can be used to copy the mailbox content (folder structure , messages and rules) to the new mailbox in the new site.
  • When an organization changes its structure, either breaking up the current Microsoft Exchange organizational unit into a number of smaller ones or merging organizational units. In either of these situations, mailboxes need to be moved into new sites (and possibly to different organizations).
  • When an organization is moving from a pilot Microsoft Exchange Server implementation to a production roll-out and they require mailboxes to be moved between these two systems. This tool is particularly useful in this situation when a large number of users need to be moved.

The tool assumes that a mailbox exists in the new site/organization and it will copy folders and messages into this new mailbox. Since a period of time can elapse between copying the mailbox content from the mailbox to the personal folder store and then copying from the personal folder store to the new mailbox, the old mailbox is not deleted. Rules are created on the old mailbox to forward messages onto the new mailbox. It is the responsibility of the Microsoft Exchange Administrator to delete the old mailboxes.

Note The Mailbox Migration tool will only run on Windows NT Workstation. Also, it is not possible to run multiple copies of the Mailbox Migration tool on the same workstation. Although it is possible to run the application on different workstations against different servers at the same time, this can impact the configuration.

To run the Mailbox Migration tool

  • You need a working Microsoft Exchange Client that can connect to both the pilot and production servers to be used. There are no limits on the mailbox size (on either the pilot or production systems). However, the client workstation should have at least 100MB of free space for creation of the .pst file.


Installing the Mailbox Migration Tool

To install the Mailbox Migration Tool

  • From the Exchange\Winnt\<platform>\Admin\MBMigrate directory on the Microsoft BackOffice Resource Kit, Part Two, compact disc, copy the Migration.exe file to your computer.


Using the Mailbox Migration Tool

Before running the Mailbox Migration tool, you must have mailbox owner permissions on both source and destination mailboxes. If you are migrating a large number of users, the best method is to create a Windows NT account for this purpose. Then grant mailbox ownership permissions to the recipient's container on the source and destination servers.

Setting Mailbox Permissions

Follow these steps to set permissions on the mailbox:

From the Microsoft Exchange Administrator window, choose Tools from the toolbar, then select Options.

Select Permissions, then select Show Permissions Page for All Objects and Display Rights for Roles on Permissions Page.

Selecting these two options enables you to grant the necessary permissions either to individual mailboxes or to an entire container. The following figure shows the Recipient's property page with an account (in this case the Administrators group) and the rights that have been set for this entry.


Running the Mailbox Migration tool

Verify that your workstation is logged on to an account with the necessary permissions to create profiles and open mailboxes.

Create a profile on the workstation that can be modified by the Mailbox Migration tool.

From the Start menu, choose Run.

Locate the Migrate.exe file and double-click on the filename.

Type the path name and file name of the recipient's list file that contains the recipient's name and server.

Following is the structure of the recipient's file.

<Display Name>,<Alias Name>,<Pilot Server Name>,<Production Server Name><CRLF>

For example:

Joe Bloggs,JoeB,GW-PILOT1,GW-PROD1

Mary Smith,MarySm,GW-PILOT1,GW-PROD1

The file can contain any number of recipients and any combination of servers.

Choose Start.

When the file is found, the Mailbox Migration tool begins processing the first recipient in the file.

The following figure illustrates the Mailbox Migration Tool user interface.

For each recipient in the file, the application performs the following functions.

  • Modifies the migration profile so it can open your mailbox and create a new .pst file on the workstation.
  • Logs on to this profile.
  • Copies all the messages and all subfolder trees in the mailbox Inbox folder to the .pst Inbox folder.
  • Copies all the messages in the mailbox Sent Items folder to the .pst Sent Items folder. You can ignore any subfolders, unless it is easier to copy everything.
  • Copies all the other folders, subfolders, and messages that you have created from the mailbox to the .pst store. However, any custom views, filters, rules, and permissions will not be copied.
  • Logs off the profile.
  • Copies the folders and messages from the .pst to your mailbox on the production server. Note that the Inbox of the new server will be checked. If there are any messages in this folder, the mailbox will not be migrated and an error message is generated. The Inbox is always the first folder to be migrated.
  • Deletes the .pst file.
  • If you choose the Stop button, the Mailbox Migration tool continues to process the current mailbox and then stops processing after the mailbox has been migrated, or after the mailbox migration attempt has failed due to errors.
  • Any errors generated in the process are logged to an error log.
  • The structure of the log file is as follows:

<type>,<Display Name>,<Alias Name>,<Pilot Server Name>,<Production Server Name>,<Description>,<Timestamp><CRLF>

For example:

SUCCESS,Joe Bloggs,JoeB,GW-PILOT1,GW-PROD1,Migrated No Errors,5/10/96 10:05:00
or:
FAILURE,Mary Smith,MarySm,GW-PILOT1,GW-PROD1,Error Copying Messages,5/10/96 10:09:10
  • If the Migration Mailbox tool fails for any reason, you can restart the tool from the same point by using the same recipient list (as each successful migration causes the entry to be deleted).
  • To migrate single users or groups of users that were not migrated because of errors, you can create recipient list files and run the Mailbox Migration tool again.
  • When all mailboxes have been migrated in the recipient list, a message appears stating that the system has completed the migration.

Control File

The tool uses a standard comma-separated value file which contains the information required to migrate a mailbox from one server (source) to another server (destination). The control file can be created by any text editor or a spreadsheet like Microsoft Excel. There is a sample control file supplied (Sample.csv) that contains a header row and a sample line. The tool does not expect a header row in the control file, but it is easier to leave the header row in so the tool posts an error against the first record in the file.

The control file has two purposes. It is used as the input to the utility but also as the output and error log. An identical file format is created after running the utility. It marks the status of every record that has been migrated, any errors that occurred, and a timestamp showing when each migration was completed.

The fields are described below in the order they occur in the file.

SrcOrgName

The name of the Exchange Organization where mailbox <SrcAliasName> is located.

SrcSiteName

The name of the Exchange Site where mailbox <SrcAliasName> is located.

SrcAliasName

The unique mailbox identifier on server <SourceServer> (unique within the Exchange site that hosts <SourceServer>)

DisplayName

The display name as produced by the Exchange Directory Export Function.

SrcNewDisplayName

The display name used for the mailbox <SrcAliasName>. If this value is not blank, the display name is replaced with this value so that the mailboxes in both sites can be distinguished. If the value is blank, the name remains unchanged.

SourceServer

The machine name of the server where mailbox <AliasName> is located.

DestOrgName

The name of the Exchange Organization where mailbox <DestAliasName> is located.

DestSiteName

The name of the Exchange Site where mailbox <DestAliasName> is located.

DestAliasName

The unique mailbox identifier on server <DestinationServer> (unique within the Exchange site that hosts <DestinationServer>). This mailbox should already exist and have a valid Windows NT account associated with it.

DestNewDisplayName

The display name used for the mailbox <DestAliasName>. If this value is not blank, the display name of <DestAliasName> is set to this value. If this value is blank, then the display name of <DestAliasName> is set to <DisplayName>.

DestinationServer

The machine name of the server where mailbox <DestAliasName> is located.

PstUNCName

The location in UNC format where the .pst file is created or is to be found (the use depending on the value of pstBackup). The actual name of the .pst file will be the alias name of the destination mailbox <DestAliasName>.

PstBackup

If this value is "Y" then the .pst file named <AliasName> is created in location pstUNCName from mailbox <AliasName> on server <SourceServer> if the value of Status is blank. The mailbox is not migrated from the .pst file to the destination server if this value is "Y".

If this value is NOT "Y" then the mailbox <AliasName> is created on server <DestinationServer> from the contents of the .pst file located at <pstUNCName>.

SetupAutoRules

If this value is "Y" then a rule is created on mailbox <SrcAliasName> on server <SourceServer> that will set up an Auto Reply message. This message indicates that the mailbox is being migrated and message delivery will be delayed.

Additionally, a rule is created on the mailbox <SrcAliasName> on server <SourceServer> that forwards all messages to mailbox <DestAliasName>.

Both rules are created BEFORE the creation of the .pst file <pstUNCName> so that any new messages that are sent to the mailbox during the migration will get forwarded. However, the rules should not be copied to the new mailbox.

DoSentDeletedItems

If this value is "Y", then the Sent Items folder (and all sub folders) and the deleted items folder (and all its sub folders) will be copied. Otherwise, they will be ignored.

Status

This value will be blank, "Partial", "Complete" , "Failure", or "CRITICAL". The value is initially blank and is filled in by the utility after a mailbox has been migrated. A blank indicates a record that has not been migrated yet. "Partial" indicated that the mailbox has been successfully copied to a .pst file. "Complete" indicates that the mailbox has been fully migrated from one server to another. "Failure" indicates that some error has occured. "CRITICAL" indicates that an error has occured, causing a mailbox to be left in an inconsistent state, and requires attention.

Description

This is a text string that generally will contain error messages.

TimeStamp

After a migration phase, this field contains a timestamp of the mailbox when the migration was completed.


Troubleshooting the Mailbox Migration Tool

Following are troubleshooting tips to use when working with the Mailbox Migration tool.

  • Using the .csv file format. Some organizations have commas in their display names. If you use Microsoft Excel to create the .csv file, Excel automatically places quotation marks around any values that have commas in them. The tool treats a value surrounded by quotes as a single value.
  • Using the Tools.Clean Mailbox utility in the Microsoft Exchange Administrator. This removes only messages; it does not remove folders. Therefore, if a mailbox fails to migrate, the temporary folder will still exist. Trying to migrate after a cleanup causes a failure again, because the utility recognizes that the special temporary folder is present in the mailbox.
  • Deleting folders with the client application. If a mailbox has special folders that cannot be deleted by the client application (this may happen for Outlook users, because Outlook creates special folders for Calendar, tasks, and so forth, and will not let you delete them) and a migration fails, deleting the mailbox and recreating it is the best option.


Mailbox Statistics Tool

You can use the Mailbox Statistics tool (Storstat.exe), to gather data about mail use patterns. This MAPI application analyzes a responding user's set of personal folders and then develops statistics, such as the number of rules in a folder and the amount of mail sent and received daily. You can gather statistics about users who run Microsoft Exchange with either the Windows 95 or the Windows NT Workstation operating system.

You can export this data into several formats, including .txt and .csv. A Microsoft Visual Basic macro that runs under Microsoft Excel is also included. You can use this macro to explore Mailbox Statistics results in more detail. Using Microsoft Excel, you can customize column names, convert the data into a chart, or otherwise manage Mailbox Statistics results.

You can run Mailbox Statistics anytime. A frequency of about once every six months is typical. You can use it to establish use patterns, to determine when a server load should be rebalanced, or when you need data for the Microsoft Exchange Server Load Simulator (LoadSim) that more closely reflects your users.

The Mailbox Statistics tool creates some load on the server, so it's best not to use it during peak hours. Also, you can divide your users into groups and spread your study over a day's time. For example, you can survey your accounting staff at 9 A.M. and your marketing staff at 11 A.M.


Installing Mailbox Statistics

You install Mailbox Statistics by copying its files from the Microsoft BackOffice Resource Kit, Part Two compact disc to a Microsoft Exchange Server computer.

To install Mailbox Statistics

  • From the Exchange\<operating system\platform>\Admin\Storstat directory, copy all the files in the directory to your Microsoft Exchange Server computer.

This directory contains StorStat.exe, which can be used by Windows 95 and Windows NT Workstation users.


Using Mailbox Statistics

When you use Mailbox Statistics, you set up an administrator's mailbox for collecting results and send the tool to your users to run it against their sets of personal folders. When users submit a number of results, you can run the tool in administrator mode and export results to a variety of output formats. Before you send the tool to your users, you can test it with a small subset of about 10 people to ensure the tool works as expected and to become familiar with the different kinds of results.

Note Mailbox Statistics can detect only Microsoft Exchange Server distribution lists (DLs).

If the Save Items to Sent Mail option is not selected in a user's Microsoft Exchange setup, then Mailbox Statistics cannot determine the number of messages sent per day. You can ask the test group to select this option for at least seven days before the study to collect enough information to use.

To use Mailbox Statistics:

  • Set up an administrator's mailbox that will be used to receive the data
  • Send a message with Storstat.exe attached to the users to be surveyed. Those users double-click an icon in the message to run it.

    Note Storstat.exe is supported only for users on Windows 95 or Windows NT Workstation.

To set up the administrator's mailbox

Using the Microsoft Exchange Server Administrator program, create a mailbox with the display name StorStat.

Set permissions on this mailbox according to your organization's procedures, so that the Microsoft Exchange Server administrator's account has user permission on this mailbox.

Results appear as MAPI messages with the subject "UserName UserResults." You can use the Inbox Assistant to forward or copy results to another folder.

To send mailbox statistics to users

From the Microsoft Exchange Client Compose menu, choose New Message.

In the message body, type instructions for your users.

From the Insert menu, choose File, and then attach StorStat.exe to the message.

It appears as an icon in the message.

Users can be concerned about using the tool if they believe it will alter, damage, copy, or intrude in any way on their sets of personal folders. For this reason, you can include information to reassure them that no information is read or copied, no damage is inflicted on their data, and no changes are made to their data when this tool is running.

How a User Works with Mailbox Statistics

The user opens the message and starts a copy of the tool, which opens the Message Stores Statistics Analyzer dialog box listing all the user's personal folders. At least one message store must be selected before analysis can be started.

By default, all personal folders are selected. The user can choose Clear All to cancel the selection and then select specific folders to analyze, or choose Select All to select all the personal folders. If the user chooses Exit, no analysis is performed.

When the user chooses Start Analyzing, the tool opens and analyzes every personal folder file owned by that user. The tool then generates statistics, including the number of folders, the number of rules, and the amount of e-mail per day in each folder. A progress bar and the folder names are displayed as messages are processed.

When the Mailbox Statistics tool finishes analyzing the folders, it displays the following message: "Results have been automatically sent to your administrator. Thank you for your cooperation." Optionally, the user can also save the results. When the user deletes the announcement message, StorStat.exe is also deleted.

Running Mailbox Statistics in Administrator Mode

This procedure assumes that an administrator's mailbox (named StorStat) has been created and is available to collect results from users. You can check on the number of responses by opening the Inbox and viewing the number of messages containing "UserResults." When enough responses have been gathered, you can tabulate them by running the Mailbox Statistics tool in administrator mode.

If you have results generated by an earlier version of the tool, store them separately from later results. With the results separated, you should receive no error messages caused by using the tool on mixed-version generated results.

If you want to use the macro included with Mailbox Statistics, save your results in the Microsoft Excel .csv file format.

To run Mailbox Statistics in Administrator mode

At the command prompt, type:

storstat.exe -a

Set the default messaging profile to the Mailbox Statistics administrator's mailbox, or select the profile.

You'll see a progress bar move as messages are processed. When all messages are processed, the Summary Results dialog box appears.

Choose Save As to save results in a location under a file name you specify, or choose Exit to disregard these results.

Exporting results

When the Mailbox Statistics tool completes its analysis of each set of personal folders, it sends a message to the administrator's mailbox you set up for collecting the results. When you run the tool in administrator mode, you can save your results as many times as you want, using different file types.

To export your results

Run Mailbox Statistics in administrator mode.

In the Save As dialog box, select a file type for your results.

Interpreting results

Remember that the Mailbox Statistics tool works with available data. For example, if a few users empty the Deleted Items folder when quitting Microsoft Exchange, and others do not, you can see wide differences between the statistics calculated from the Deleted Items folder. Moreover, Forward and Reply may not be computed as expected with localized Microsoft Exchange clients because the logic looks for RE: and FW: characters.

The first time you review the results, use the following example to become familiar with the local source of each statistic.

Sample Mailbox Statistics results

The following two sections list captions that precede each statistic the Mailbox Statistics tool displays. The first illustrates statistics from a single set of personal folders. The second illustrates statistics from combined sets of personal folders collected in an administrator's mailbox.

If the caption is self-explanatory, no note is included. If a note is included, it follows the caption and is enclosed in brackets. Notes either define terms or clarify logic.

**************************************************
Service Provider: Personal Folders.
Message Store: Archive.
**************************************************
Total msgs in entire store: 575.
Total msgs in received mail folder: 80.
[By default, the received mail folder is the Inbox.]

Total msgs in sent mail folder: 10.
[If this number of 0, it's possible the Save Mail in Sent Items option has been turned off. If this option is off, then a number of other statistics related to outgoing mail will also be 0.]
Total msgs in Deleted Items folder: 67.
Total number of non-standard top level folders is 21.
[A standard folder cannot be deleted by a user, and includes the Inbox, Sent, Deleted Items, and Outbox folders.]
Average number of subfolders of top level folders is 0.12.
[The total number of folders is divided by the total number of subfolders.
Average depth of top level folders is 0.04.]
[Depth implies how "far down" subfolders exist. For example, an Inbox with a subfolder would generate a depth of 2.]
Total msgs in msg store with at least one attachment is 118.
[An attachment can be a file, a message, or a link.]
Percentage of the total msgs in the store that contain at least one attachment is 20%.
[Number of messages with attachments divided by total number of messages, converted to a percentage.]
Average msgs sent per day is 0.00.
[This average is calculated using the number of days in the sample.]
Average msgs sent per day (real) is 0.00.
[This average is calculated using all the days between the first and last date that a message was sent. This number also includes days when no messages were sent. So, for example, if a user sent mail on Monday, Wednesday and Friday, 'sent per day' would be divided by 3 and 'sent per day (real)' would be divided by 5.]
Largest number of msgs sent a day is 0
[A day is defined as midnight to midnight and is not configurable.]
Largest number of recipients on a message is 0
[A recipient can be either a single recipient or a single distribution list (DL).]
Average number of recipients on all sent msgs is 0.00.
[Total number of recipients on sent messages divided by the number of messages sent.]
Average number of DL recipients on all sent msgs is 0.00.
[Total number of DLs on sent messages divided by the total number of messages sent. If you are using a different mail system to control DLs, then the number sent to DLs will be lower than expected. Mailbox Statistics detects only Microsoft Exchange Server DLs.]
Percentage of the total msgs sent to at least one DL is 0%.
[Number of sent messages with at least one DL divided by the total number of messages sent.]
Total msgs sent to at least one DL is 0.
Average number of replies per day is 0.00.
[Number of replies, message subject prefix equals RE:, divided by the number of days messages were sent.]
Average number of forwards per day is 0.00.
[Number of forwards, message subject prefix equals FW:, divided by the number of days messages were sent.]
Average number of replies per day (real) is 0.00.
[Number of replies, message subject prefix equals RE: divided by the total number of days surveyed.]
Average number of forwards per day (real) is 0.00.
[Number of forwards, message subject prefix equals FW:, divided by the total number of days surveyed.]
Percentage of sent messages that were replies is 0%.
[Total number of sent messages that were replies divided by the total number of sent messages.]
Percentage of sent messages that were forwards is 0%.
[Total number of sent messages that were forwards divided by the total number of sent messages.]
Combined size of all messages in message store 19318K.
[Cumulative size of all messages as reported by MAPI. Don't be concerned by the relationship between the size of the private information store (Priv.edb) database file and the total message store size reported by Mailbox Statistics, because they do not correspond one-to-one.]
Folder with the largest combined size of messages had 9062K in it.
[This is the sum of all message sizes in a single folder. It does not include subfolder totals.]
Largest # of messages in any folder 106.
Average size of messages per folder 689.93K.
[Total size of all messages divided by the number of folders in a store.
Total number of folders in message store 28.
[Total number of messages in the message store, including the standard folders, Inbox, Outbox, Sent Items, and Deleted Items.]
Max depth of folders is 2.
[Depth implies how "far down" subfolders exist. For example, an Inbox with a subfolder generates a depth of 2.]
Average # of msgs received per day 6.75.
[Total number of messages in a store divided by the number of days during which a message was received. This number can be skewed if a message is copied multiple times within a store or if the Empty the Deleted Items Folder upon Exiting option is selected.]
Average # of msgs received per day (real) 3.28.
[Total number of messages in a store divided by the total number of days.]
Maximum # of msgs received in a day 54.
Number of Inbox rules is 0.
[Number of Inbox Assistant rules including Out of Office Assistant rules.]
**************************************
Results for provider: Combined Message Stores.
**************************************

Number of result messages for this provider: 0.
Average # of messages in Inbox: 0.0.
Average # of messages in Sent Items: 0.0.
Average # of messages in Deleted Items: 0.0.
Highest number of additional folders of any message store: 0.
[This number excludes the standard folders, which are Inbox, Outbox, Sent Items, and Deleted Items.]
Lowest number of additional folders of any message store: 0.
Average number of additional folders for all message stores: 0.0.
Number of msgs total for all message stores: 0.
Percentage of those msgs that contain at least one attachment: 0%.
Largest number of msgs in any message store: 0.
Average number of msgs per message store: 0.0.
Average number of msgs sent per day: 0.0.
Average number of msgs sent per day (real): 0.0.
Highest number of msgs sent per day: 0.
Lowest of the maximum sent per day: 0.
[If this number is 0, a user may have either emptied the Sent Items folder or sent no mail in a day.]
Average number of recipients per sent msg: 0.0.
Average number of distribution lists per sent msg: 0.0.
Total number of messages sent to at least one DL: 0.
Percentage of total messages sent to at least one DL: 0%.
Avg # of subfolders of top level folders: 0.0.
Avg depth of top level folders: 0.0.
Largest # of recipients on a single message: 0.
Average # of replies per day: 0.0.
Average # of forwards per day: 0.0.
Average # of replies per day (real): 0.0.
Average # of forwards per day (real): 0.0.
Percentage of sent messages that are replies: 0%.
Percentage of sent messages that are forwards: 0%.
Percentage of sent messages that were originated: 100%.
[100 percent minus the percentages of replies and forwards.]
Combined size of all messages: 0K.
Average message size: 0.0.
Folder containing largest size of messages: 0K.
Folder containing largest # of messages: 0.
Average # of messages per folder: 0.0.
Total # of folders: 0.
[Total number of folders for all clients, including the Inbox, Outbox, Sent Items, and Deleted Items for each.]
Avg # of folders per message store: 0.0.
Largest # of folders per message store: 0.
Deepest folder tree: 0.
Avg # of messages received per day: 0.0.
Avg # of messages received per day (real): 0.0.
Largest # of messages received per day: 0.
Total # of Inbox rules: 0.
Largest # of Inbox rules: 0.
Avg # of Inbox rules: 0.0.

Questions and Answers

The following are common questions and answers about the Mailbox Statistics tool:

Q: Why haven't I received any results in the administrator's mailbox?

A: Check the installation of the Mailbox Statistics tool, including these verifications:

  • The administrator's mailbox name is correct.
  • Instructions and StorStat.exe were received by the users.
  • At least one user successfully completed the survey.
  • Microsoft Exchange Server is transferring e-mail successfully.

Q: Why didn't we receive all the results?

A: Each user can decide whether to run Mailbox Statistics. Some time may lapse before all the results are sent, especially if you gave no deadline, or if some users are away from the office. If the number of results is low, verify that all users received the instructions and the Mailbox Statistics tool, and then send a reminder to run the survey.

Q: Why can't Windows for Workgroups or Windows 3.1x users run the tool?

A: Mailbox Statistics is a 32-bit tool. It can be used only with Windows 95 or Windows NT Workstation operating systems.


Mailstorm Tool

The Mailstorm tool is designed to assist in testing the Microsoft Exchange message transfer agent (MTA) or any other message transfer agent accessible by MAPI. This tool is often used for stress testing, but can also be used to compare delivered messages for content integrity. Messages are altered as they are touched by different components of a messaging system. Mailstorm can be used to compare the difference between the original message Mailstorm sent and the message Mailstorm received. Mailstorm is a MAPI client and sends and compares mail through the MAPI interface.


Installing Mailstorm

To install the Mailstorm tool

  • From the Exchange\<operating system\platform>\Admin\Mailstrm directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Mailstrm.exe to your computer.


Using Mailstorm

The Mailstorm tool supports many command-line options that enable you to run the Mailstorm program automatically. Following are the command-line options you can use when running Mailstorm.

To run the Mailstorm tool

At the command prompt, type Mailstrm<option>.

Press Enter.

The following table lists the command-line options available in Mailstorm, and their descriptions:

Option | Description
-u<ProfileName> | Profile name for logon.
-p<Password> | Password.
-f<ConfigurationFile> | Path to configuration file. Must contain extension.
-a | Auto run and exit when done. Mutually exclusive with -v.
-v | Auto compare and exit when done. Mutually exclusive with -a.
-lLogFile | Path and file name to log file.
-mPathToMessages | Path to messages to change test case data about message location.
-tTimeout | Time to wait for messages in Inbox, for verification.
-nTestCaseNumber | Test case number for printing to log.
-? | Usage Help.

Overview of the Mailstorm User Interface

Menus

The menu bar includes the following menus:

  • File Menu — The File menu includes the following familiar commands: New, Open, Save, Save As, and Exit.

    You can also choose from the following commands on the File menu:

Command | Description
Logon | Prompts you for a profile name and then opens a MAPI session according to the profile you selected. It is recommended that you log on before setting any options, because certain options, such as specifying an Address List, require a valid MAPI session to function.
Logoff | Select to log off the current MAPI session.
Compose Note | Calls the MAPI provider to bring up a compose note window. This enables you to create new message (.msg) files.

  • Options Menu — The Options menu enables you to set options for configuring Mailstorm, comparing messages, and logging. For more information on these options, see "Setting Message Configuration Options," "Setting Compare Message Options," and "Setting Logging Options" later in this section.
  • View Menu — The View menu provides three ways to work in the main Mailstorm Viewer. Use the Toolbar and Status Bar commands to display or hide the toolbar or status bar, respectively. Choose the Clear Log command to clear the log display in the lower section of the Mailstorm Viewer.
  • Help Menu — The Help menu has only one command: About. Choose this command to view information about Mailstorm.
Toolbar

The Mailstorm toolbar provides easy access to most menu functions. The toolbar buttons, from left to right, are: File/New, File/Open, File/Save, File/Compose Note, File/Logon, File/Logoff, Options/Configuration, Options/Compare Messages, Options/Logging, View/Clear Log, and Help/About.

Mailstorm Viewer

The Mailstorm Viewer includes a status pane, a row of buttons on the right, and a logging pane at the bottom. The status pane displays information about the current send or verification run. It also displays information about the previous send or verification run, regardless of whether a run is in progress. The buttons on the right provide control for the run. The Start button enables Mailstorm to start sending mail.

The Compare button starts a compare of mail in the Inbox. The Compare utility will recognize a message in the Inbox with a subject tagged with a file name identifier. Mailstorm will show the difference between the message in the Inbox and that identified by the subject. The Pause and Stop buttons pause or stop the current action.

Setting Message Configuration Options

To set message configuration options

Choose Configuration from the Options menu or click the Configuration button.

Set options. The following options are available:

Option | Description
Files | Selects the message files you want to send.
Duration | Specifies the length of time Mailstorm sends messages.
Delays | Specifies the delays that Mailstorm uses when sending mail.
Recipients | Selects message recipients or chooses not to modify the recipient list.
Subject | Modifies the subject header of a message.
Message Properties | Sets the properties for each message that Mailstorm sends.
Settings | Sets general options for comparing messages.

Selecting Message Files to Send

To select message files to send

Select the Files tab.

Select the directory where the message files are currently stored by choosing Set Path. Note that you must choose Set Path to specify the path; you cannot edit the path by typing a path name in the Directory box.

After you confirm the directory path, all message files with the .msg extension that are available in that directory will appear in the list on the left. The list of files on the right is the current group of files to send.

To modify this group by adding or removing messages from the list on the left, choose Add, Add all, Remove, or Remove all.

Specifying Time Length for Sending Mail

To specify the time length before Mailstorm sends mail

Select the Duration tab.

Specify the duration. The duration can be specified as units of time, quantity of mail sent, or time length equals forever.

Specifying Amounts of Time Mailstorm Uses to Send Mail

To specify the amount of time Mailstorm waits between sending individual messages or group messages

Select the Delays tab.

Specify the delay values.

  • The first delay value indicates the amount of time that Mailstorm waits after sending one message and before sending the next message in the group. (A group is the list of message files specified in the Files tab).
  • The second delay value indicates the amount of time that Mailstorm waits after sending one group of messages and before sending the next group.

Selecting Message Recipients

To select message recipients

Select the Recipients tab.

Choose To, and then select the recipients you want from the list. Note that you must be logged on before you can select recipients.

Set options. The following options are available:

Option | Description
Use these recipients instead of .MSG recipients | Select this option to instruct Mailstorm to use the recipients just selected. .
Don't change .MSG recipients | Select this option if you do not want Mailstorm to modify the recipients on the message files. This means that Mailstorm ignores the recipient list displayed in the Recipients tab. You should also select the Resolve Name during submit option (described below) because the address list on the message files may be dated. If you do not select the Resolve Name during submit option, an error may occur on submit.
Append these recipients to .MSG recipients | Select this option to instruct Mailstorm to append selected recipients to those already existing on the message..
Resolve Name during submit | Select this option if you want Mailstorm to resolve the recipient list on each message before sending it. As mentioned earlier, it is recommended that you select this option if you are using recipients already on a message file, because the recipient list may be no longer valid or it may not have been previously resolved.

Note At least one recipient must be specified for each message (either added by Mailstorm or previously present in the message file), or an error will occur when Mailstorm attempts to send the message.

Modifying the Subject Header of a Message

To modify the subject header of a message

Select the Subject tab.

Set options. The following options are available:

Option | Description
Use this subject instead of .MSG subject | Select this option and type a new subject in the Subject box to replace the subject currently displayed in the message.
Append numeric identifier to all subjects | Select this option to add a unique identifier to the subject of each message. This enables messages to be differentiated from each other in the same run and in different runs.

Setting Properties for Messages Mailstorm Sends

A selection of message properties can be set prior to Mailstorm submitting the message. These properties can also be set by using the Microsoft Exchange Client. The Mail system should handle the option correctly.

You can set the following options for messages that Mailstorm sends: Message delay in sending, Message expiration, Copy to Sent Items folder, Importance, Sensitivity, Attachment type, Read receipt request, and Proof of delivery request. The Attachment Type option enables selection between different SMTP types of attachment forms.

To set properties for messages that Mailstorm sends

  • Select the Message Properties tab, and then set options.

Setting Compare Message Options

To set options for comparing messages

Choose Compare Messages from the Options menu or choose the Compare Messages button.

Set the options described below.

Settings

To set general options for comparing messages

Select the Settings tab.

Set options. The following options are available:

Option | Description
Modify Message Subjects during submit with "file name identifier" | Select this option to tag submitted messages with an identifier. Only received messages that have this identifier can be compared. When this option is selected, Mailstorm adds the path of the original message file to each message submitted. Mailstorm parses this path (called the subject file name identifier) to compare and locate the source message file.
Compare against | Select an option under Compare Against to specify the source path of the original messages. Select the File identified on the subject (original) option to use the full path from the subject file name identifier to find the source file. Select the Using specified path + file name (pre-verified "Master") option to override the path from the subject file name identifier and specify a different path. This option is useful when the file you want to compare is not the same as the file sent.

Exclude Properties

This feature is useful because some properties (such as submission time) differ between the tagged message in your Inbox and the message file you are comparing it against.

To select the MAPI properties that are excluded from the Compare against option

Select the Exclude Properties tab.

There are four exclude lists. The drop-down list box displays the list that is currently being modified. The list on the left displays standard MAPI properties. The list on the right displays the currently selected properties.

  • To modify the list of currently selected properties, select the properties that you want to add or remove, and then choose Add, Remove, or Remove all.
  • To specify a property that is not a standard MAPI property, type the 8-digit hexadecimal value of the property tag, and then choose Add Custom. The property tag will appear in the list on the right.
Exclude Ranges

This feature is useful when you're comparing fax attachments because it enables the date stamping to be excluded while the actual content is compared. The range is specified as a zero, based on low and high bounds of exclusion. Currently, the only property that can have a range excluded is PR_ATTACH_DATA_BIN.

To specify ranges to exclude when comparing particular properties

  • Select the Exclude Ranges tab.

Setting Logging Options

To set logging options

  • Choose Logging from the Options menu or choose the Logging button.
Logging

To set logging levels

Select the Logging tab.

Set the level of logging detail you want at the interface level and at the file level. The level of detail can be set to: None, Minimum, Medium, and Maximum.

  • The interface level determines what level of logging detail appears in the Mailstorm Viewer logging pane.
  • The file level determines what level of logging detail is written to a file. To log to a file, select the Log to file option. To specify the file to use for logging, choose File.
Property Logging

To log the message properties of all messages in the Inbox of the currently logged-on user or the currently selected group

  • Select the Property Logging tab.

    To view the logged properties, you must set the logging level to Medium or Maximum for the interface or the file, or both.


Management Chain List Tool

The Management Chain List tool enables you to specify a user's e-mail alias through the command line and returns a formatted list of the management chain from the user's level up to the CEO.


Installing the Management Chain List Tool

There is only one step to installing the Management Chain List tool. However, before you install the tool, make sure that you:

  • Have already created a default Microsoft Exchange profile; or
  • Create a new profile by using a name of your choice and specify it by using the /p command-line switch.

To install the Management Chain List tool

  • From the Exchange\<operating system\platform>\Admin\MgmtList subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the Mgmnt.exe file to a directory on your computer.


Using the Management Chain List Tool

The Management Chain List tool requires a MAPI profile to report on the management chain list. If no profile is specified, the tool uses the default profile created by your e-mail application. As shown below, you can also create your profile by using the Control Panel.

To create a new MAPI profile

In the Control Panel, double-click the Mail icon.

Select the Services tab, and then select Microsoft Exchange Server from the list.

Choose Show Profiles.

Tool Syntax

To use this tool, you can provide optional blanks between options and their values (for example, /pProfile). Remember to use double quotation marks when you type values that contain blanks.

In addition to using the command-line syntax noted below, you can also obtain this information by typing MGNTLIST /? at the command prompt. Following is the typical syntax usage for the Management Chain List tool.

MGNTLIST [/p Profile] [/s Server] [/i Site] [/e Enterprise] Name [Name]...

Parameters
  • Profile — MAPI profile name (default = Default profile)
  • Server — Server to log on to (default = Local server)
  • Site — Site to log on to
  • Enterprise — Enterprise to log on to
  • Name — The display or e-mail alias name to search on managers for Server, Site, and Enterprise are ignored if a profile has been provided.

Output Format

The Display Name, Alias, Title, Department, and Phone [or Phone2] are listed for the user, the user's manager, the second-level manager, and so on.

If a manager's display name is missing within the Microsoft Exchange global address list (GAL), an error message is generated as part of the formatted management chain list.

The Management Chain List tool runs only through a command line.

  • "MGNTLIST name" logs on by using the default profile.
  • "MGNTLIST /pProfile name" uses the specified profile (and ignores any other switches).
  • "MGNTLIST /sServer name" uses the "MGNTLIST" profile to log on to the System Attendant. If the MGNTLIST profile exists, it will be used. Otherwise, a profile with this name will be automatically created and used.

The tool uses an upper boundary of 20 levels to prevent an infinite loop in finding users who report to themselves. Although this number is arbitrary, it should not create a problem because the management hierarchy for most users is rarely above 8 to 10 levels.


Mapindl Tool

The Mapindl tool enables you to attach a Lotus Notes Document Link (DocLink) to a Microsoft Exchange Server message when using Active Messaging. Mapindl.dll contains an OLE Automation server object that enables this process.

The Mapindl.dll object is useful in situations where Lotus Notes workflow applications require the use of a messaging infrastructure for user notifications. Previously such applications required the activation of NotesMail to route and deliver these messages. When Microsoft Exchange Server was intended as the primary messaging transport, activating NotesMail resulted in redundant messaging infrastructures.

When LotusScript uses Active Messaging and Mapindl.dll, Microsoft Exchange Server can be used as the messaging transport in Lotus Notes applications. This eliminates the need for NotesMail and simplifies the overall system architecture.

Although Active Messaging and LotusScript can be used to send Microsoft Exchange messages from Lotus Notes applications, before Mapindl.dll, links could not be attached to Lotus Notes documents programmatically. This functionality is packaged as an OLE Automation object (Mapindl.Attach) for ease of use in Active Scripting. A type library (Mapindl.tlb) is also provided for access from other development languages.


Installing Mapindl

Use the following procedure to install Mapindl.

To install Mapindl

From the Exchange\<operating system\platform>\Developr\MAPIndl directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Mapindl.dll to the Windows\System directory on your computer.

Make sure that Msvcrt.dll and Mfc42.dll exist somewhere in your computer's path because these files are required before you can run Mapindl.dll. If you do not have these files, they can be obtained from Microsoft Visual C++ version 4.2.

Note Mapindl.dll only needs to be present on the computer that originates the MAPI message and attaches the Lotus Notes DocLink. Standard OLE activation in Windows 95 and Windows NT will be used to activate Lotus Notes and display the document.

At the command prompt, switch to the directory where Mapindl.dll resides.

Type the following command:

REGSVR32 MAPINDL.DLL

Typing this command registers the DLL with your system. You can test the installation by starting the Lotus Notes database (Mapindl.nsf), and composing and saving a main topic document. After you reopen the document, select Send MAPI Notification.


Using Mapindl

Before using Mapindl, make sure that one of the following development environments exists on your computer.

  • Microsoft Exchange Client 4.x
  • Lotus Notes Client 4.x

You can use the Mapindl.Attach object provided by the Mapindl tool as part of a LotusScript action in a Lotus Notes database application. Likewise, standard Active Scripting (Microsoft Visual Basic Script or Microsoft Visual Basic for Applications) can be used in the same way from other applications. However, other means must be used to acquire the appropriate Lotus Notes identifier strings.

The following steps are typically required to implement Mapindl.

To enable Microsoft Exchange Server notifications of Lotus Notes applications

Create or identify a Lotus Notes application that you want to enable Microsoft Exchange Server notifications. This application should be located on a server so that the application's links remain valid from multiple computers. However, you can also use a local database for development and testing.

Configure a Microsoft Exchange Server MAPI profile to connect to a valid messaging system. If profile selection is enabled, the profile name can be used in Active Messaging to prevent repeated prompts during log on.

In the Lotus Notes application, create an action in a view or form that can run a LotusScript. In the script, perform the following steps:

  • Obtain the necessary database, view, and document IDs of the link target.
  • Create an Active Messaging session from the MAPI.Session object.
  • Log on to the correct messaging profile by using the .Logon method.
  • Create a new MAPI message in the default mailbox outbox by using the .Outbox.Messages.Add method.
  • Set the desired message properties for the recipient, subject, and body of the message.
  • Attach the desired Lotus Notes DocLink to the message by using the objMAPINDL.AttachLink method.
  • Send the message.
  • End the MAPI session.


Troubleshooting Mapindl

The following are common errors that you may encounter when building systems using Mapindl.

  • "Cannot create automation object" ¾ This error is generated on a call to CreateObject(Mapindl.Attach) and Mapindl.dll is not correctly registered on the client computer making the call. Check the HKEY_CLASSES_ROOT hive in the directory for the correct Mapindl.Attach configuration. Try rerunning RegServ32 to reregister the OLE object.
  • "The source application for the object could not be started"¾This error is generated when a user attempts to activate (double-clicks) the resulting Lotus Notes Link from the Microsoft Exchange Client. Either the linked document no longer exists in the database, or the targeted Lotus Notes application is not present on the user's computer. It typically does not mean that Lotus Notes could not be started.

For more information, see the following files on the Microsoft BackOffice Resource Kit, Part Two compact disc:

  • Mapindl.tlb — The type library
  • Mapindl.nsf — The sample Lotus Notes database
  • Mndlapi.doc — The application programming interface (API) documentation for the object


MAPIsend Tool

The MAPIsend tool (Mapisend.exe) is used to send messages with optional file attachments through Microsoft Exchange Server from a Windows NT Workstation or Windows 95 command prompt.

Note The MAPIsend tool (Mapisend.exe) was formerly known as the Command-Line Mail Sender Tool (Sendmail.exe). This program is also available in the Microsoft Mail Resource Kit.

Computers running Windows NT Workstation or Windows NT Server unattended can better communicate their status proactively, rather than constantly being polled by remote performance monitors or operations staff using Windows NT Server administration tools. The MAPIsend tool was developed to enable the following tasks to be reported to an operations group using standard Microsoft Exchange Server messages:

  • Performance Monitor alerts
  • Tape backup job status
  • Disk quota information (using Diruse)

Microsoft Exchange administrators can run this program automatically, by using the AT Scheduler in Windows NT or the Winat.exe program included in the Windows NT Resource Kit. This section explains how to send mail by using Mapisend.exe with the AT scheduler.

Programs scheduled with the Windows NT AT scheduler are run by the Windows NT Schedule service. To send mail to a Microsoft Exchange mailbox with the Mapisend.exe program, you must use a domain account to start the Schedule service. By default, the service starts by using the LocalSystem account.


Installing MAPIsend

Before you can install the Command-Line MAPIsend tool, you must have either Microsoft Exchange Server or Microsoft Exchange Client running on your computer.

To install the Command-Line MAPIsend

  • From the Exchange\<operating system\platform>\MAPIsend directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy MAPIsend.exe to your working directory or somewhere in the system path.

If you want to run MAPIsend.exe using Windows NT Workstation, you need to set up a new account for MAPIsend.exe to run under as follows:

  1. Log on to a Microsoft Exchange Server as a domain account.

  2. Create a new Windows NT account that MAPIsend.exe can use to access the Microsoft Exchange Services.

  3. Create a profile for the new account.

  4. Make the domain account you are logged on to the Schedule+ service logon account.

  5. In the Administrator program, grant the new account the Send As or Mailbox Owner permission on the Permissions tab.


Using MAPIsend

The following steps explain how to use the Mapisend.exe program with the Windows NT AT scheduler.

Note To have AT scheduler successfully run the Mapisend.exe program, you must be logged on to Windows NT as a DOMAIN\USER. Also, this user must be the account that starts the Schedule service. It too, must have access to the mailbox that Mapisend.exe logs on to.

To run the MAPIsend tool

Log on to Windows NT with a domain account, for example DOMAIN\USER.

In Control Panel, double-click the Services icon.

Select the Schedule service from the list, and then choose Startup.

In the Log On As section, select This Account, and then left-click the ellipsis to display a list of domain users.

Select DOMAIN\USER.

Type the password for DOMAIN\USER in the Password dialog box, and then type it again in the Confirm Password field.

In the Startup Type section, select Automatic. This starts the service automatically when the computer is restarted.

Choose OK, and then close the Services dialog box.

In Control Panel, double-click the Mail and Fax icon.

Create a profile with the name SENDMAIL. Add the Microsoft Exchange Server service to the profile. Make sure that the Windows NT account DOMAIN\USER that was specified to start the Schedule service has permissions to open the Microsoft Exchange mailbox specified in the profile.

In the Administrator program, assign SendAs permissions to the mailbox you selected in Step 10. Make sure that you select the correct options when you choose Options from the Tools menu, and then select the Permissions property page. If you have chosen the correct options, the Permissions property page appears for each mailbox object, along with its corresponding user rights.

Command-Line Syntax

The following command can then be used with the AT scheduler or the Winat.exe program:

MAPISEND.EXE -u <profile name> -p <password> -r <recipients> -s <subject>

Where <profile name> is the name of the SENDMAIL profile you created in step 10. The MAPIsend tool requires double quotation marks around its parameters if there are spaces in the names.

Note You must also specify the profile, password of the account running the Scheduler service, and the recipient. There is no off switch that saves a copy of messages sent to the Sent Items log. Also, Mapisend.exe requires a password. The password specified with the -p option is only to prevent the Mapisend.exe program from failing.

For more information on the command-line switches available with Mapisend.exe, see the documentation that accompanies this tool.

How MAPIsend Works

MAPIsend takes the command-line arguments you pass it and calls three basic MAPI functions: Logon, SendMail, and Logoff. The tool then pauses for one second and lets other MAPI threads, namely the Spooler, deliver your message before it quits. This is done so that the client does not need to be loaded to use the MAPIsend tool, and the message is delivered before MAPIsend stops.

Example

In this example, a message from user RISNT01 is sent to Technicians 1, 2, and 3 with a copy to local area network (LAN) Support. The subject is "[411] Server Alert" with a message "Disk is 90% full." The two log files are attached to the end of the message.

Instead of hard-coding the subject line and message text, you can retrieve specific details from the Performance Monitor alert with the command-line arguments %0, %1, %2, and so on, to construct a meaningful MAPIsend message.

Run the Srvany.exe tool in the Windows NT Resource Kit to set up Performance Monitor to run as a service.

Add an alert that starts when the disk drive is more than 90 percent full.

In the Alert Send window, run MAPIsend by typing the following in the Run Program on Alert box:

MAPISEND -u RISNT01 -p -r tech1;tech2tech3 -c "LAN Support" -s "[411] ServerAlert" -m "Disk is 90% full" -f c:\temp\diruse.log;c:\temp\status.log

Avoiding Recipient Ambiguity Problems

Recipient ambiguity problems can occur when using MAPIsend. For this reason, recipient names entered in the To and Cc boxes must not be ambiguous; otherwise, MAPIsend will fail.

To test for ambiguity of names

Type the recipient names in the To box of a Microsoft Exchange Client standard Send form.

Choose To, or press CTRL+K.

If the names are immediately resolved without any prompting, they are not ambiguous.

Repeat this test each time the Address Book is changed, and run the test from the computer where MAPIsend runs.


Microsoft Exchange Server Preview Pane Extension

Users running Microsoft Windows 95 or Windows NT Workstation can use the Microsoft Exchange Server Preview Pane Extension to add a third area for previewing the body of messages to the Microsoft Exchange Client Viewer. The contents of the To and Subject boxes can also be displayed in the preview pane message header, but no attachments or other boxes are available for preview. Users can set reminders on messages or folders. In addition, they can use this program to determine the size of a folder and its subfolders.

With Preview Pane Extension, users can mark messages as read, set reminders on messages or folders, automatically synchronize offline folders on a specified schedule, view messages in a fixed font, and move or copy messages or folders in the Microsoft Exchange Client hierarchy.

Users customize Preview Pane Extension by choosing Options from the Microsoft Exchange Client Tools menu, and then selecting the Preview tab. The extension dynamic-link library (DLL) for these options resides on your workstation.

Preview Pane Extension may appeal to more experienced users in your organization because it combines some of the functionality of Microsoft Schedule+ type reminder features with Microsoft Exchange Client folders and messages. However, new users will also find it easy to customize and use Preview Pane Extension.

Preview Pane Extension uses approximately 1 megabyte (MB) of space on the share where you make it available to users. Preview Pane Extension is a Microsoft Exchange Client extension that uses MAPI and supports users with Microsoft 32-bit operating systems. Preview Pane Extension supports advanced security through the Microsoft Exchange Advanced Securities Extensibility application programming interface (API). It also supports Uniform Resource Locators (URLs). When a user reads text from an Internet address in the preview pane, the text can be used as an operational Internet link if it is valid.

When an extension is added to Microsoft Exchange, another module is loaded, which can impact overall performance. The preview pane generates a remote procedure call (RPC) for each item stored on a server that is previewed by a user. Also, each window resize can cause additional RPCs. A user may notice this when working the Remote Access Service (RAS).

A Preview Pane Uninstall icon is included in the Microsoft Exchange program group when a user sets up Preview Pane Extension. Running the Uninstall program removes all Preview Pane Extension files. However, if the program fails to remove these files, you can delete the registry entries.

Preview Pane Extension stores its configuration data in HKEY_Local_Machine\Software\Microsoft\Exchange\Client\Extensions by adding the following value:

4.0;c:\Windows\tripane\tripane.DLL;1;11010010000000;1101010.

You can disable Preview Pane Extension by removing this value.

Note It is recommended that you distribute Preview Pane Extension to a small group of users for testing before making it available for wide release. A minimum of 30 days is recommended as a test period. Based on this experience, you can modify the documentation you send to users.


Installing Preview Pane Extension

To make Preview Pane Extension available to users, you need to copy the appropriate files from the Microsoft BackOffice Resource Kit, Part Two compact disc to a network share, and then install them on a client computer running Windows NT Workstation or Windows 95.

To install Preview Pane Extension to a network share

  • From the Exchange\<operating system\platform>Client\Tripane directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all files to the server share where you want users to find them.

To install Preview Pane Extension on a client computer

Connect to the network location where Preview Pane Extension is available for setup.

Double-click Setup.exe.


Using Preview Pane Extension

You can use Preview Pane Extension with Microsoft Exchange Server if you are running either the Windows 95 or Windows NT Workstation operating system. You can use it to preview the body text of messages (together with the To and Subject information), to set reminders on messages or folders, or to determine the size of a folder.

Preview Pane Extension can be customized as follows:

  • Set reminders on messages or folders.
  • Hide or display the preview pane message header.
  • Mark messages as read, either at the end of a time period, such as 5 seconds, or when you click off the message.
  • Use a filter to display only unread messages in the preview pane.
  • Synchronize offline folders automatically on a schedule.
  • Customize the client toolbar with Preview Pane Extension buttons.
  • Display messages with a fixed font.

To customize the Preview Pane Extension

From the Microsoft Exchange Client Tools menu, choose Options, and then select the Preview tab.

Select the options you want, and then choose OK.

From the Tools menu, choose Customize Toolbar, and then add the Preview Pane Extension buttons you want to use.

To display the preview pane

  • From the View menu, select Preview.

To hide the preview pane

  • From the View menu, clear Preview.

    Note If you installed the Show/Hide Preview Pane button on your Microsoft Exchange Client toolbar, you can select it instead of choosing the Preview command.

To set a reminder on a message or folder

In the Microsoft Exchange Client, select a folder or message.

From the File menu, choose Reminder.

In the Preview Pane Reminder dialog box, select the options you want, and then choose Save.

Note If you installed the Reminder button on your Microsoft Exchange Client toolbar, you can click it instead of choosing the Preview Pane Reminder command.

When you move a message or folder that has a reminder, you lose the reminder. Reminders you set are private because reminder information is stored only on your local computer.

To copy or move a folder or message

From the Tools menu, choose Options, and then select the Preview tab.

Choose Copy or Move.

From the Tools menu, choose Customize Toolbar, and then display the corresponding tool on the toolbar.

In the Viewer, select a message.

On the Microsoft Exchange Client toolbar, choose the Copy or Move button.

To determine folder size

In the Viewer, select a folder.

From the File menu, choose Folder Size.

To view a message using a fixed font

Right-click the text in the preview pane to open a shortcut menu.

From the shortcut menu, choose Fixed Font.

Preview Pane Extension Shortcut Menu

When you use the preview pane, you can find commands for each message on its shortcut menu.

To open a shortcut menu

  • In the preview pane, right-click a message. Depending on the message, the following commands are available.

Command | Description
Open | Opens the message in normal mode so that you can identify and work with attachments.
Remind | Opens the Preview Pane Reminder dialog box, where you can set a reminder for the message.
Previous | Displays the previous message.
Next | Displays the next message.
Copy | Copies selected text to the Clipboard.
Select All | Selects all text in the message body.
Find | Opens the Find dialog box.
Fixed Font | Displays the message body in a monospace font.
Stop Reading | Stops the mark-as-read countdown timer. When you choose this command, the message will not be marked as read. You can also press the esc key to stop the timer.

Options Dialog Box and Preview Tab Options Settings

The following table describes each option and preview tabl abailable to the user.

Option | Description
Show message header | Hides or displays the preview message header. The preview pane message header displays the contents of the To and Subject boxes of a message.
Mark messages as read | Marks messages as read in the preview pane. When this option is selected, you can modify the time period or defer marking messages. The default is 5 seconds. To adjust the time period, select the number in the Wait box and then type a new number.
Defer Marking until selection changes | Marks messages as read only when you click off the message. This option is available only when the Mark Message as Read option is selected. You can use the two marking options together. If you don't want messages you read using the preview pane to be marked as read, clear Mark Message as Read in the preview pane. If you want to be certain that you have read a message before it's marked, select both Mark Message as Read and Defer Marking Until Selection Changes.
Synchronize every <variable> minutes after full idle | Synchronizes your folders with their offline counterparts every <variable> number of minutes. To adjust the time period, select the time period option, select the number displayed in the box, and then type a new number. Before you can set a synchronization default time period by using Preview Pane Extension, you must create at least one offline folder.
Process secure Messages | Processes secure messages in the preview pane. Secure messages have been encoded using the Microsoft Exchange Client Encrypt Message Contents and Attachments feature.
Reminder Administrator | Opens the Preview Pane Reminder Viewer, where you can review your reminders.
Copy/Move Buttons Box | Copies or moves a message to a folder. You can also specify an action to automatically follow any copy or move, such as opening the item below it, returning to Microsoft Exchange Client, or doing nothing. Choose New or Modify to open the Button Properties dialog box, and then select the options you want. Choose Delete to delete a button. Before any options you set in the Copy/Move Buttons box are available, you must customize your Microsoft Exchange Client toolbar by choosing the Customize Toolbar command on the Tools menu. Preview Pane Extension buttons are in the Customize Toolbar dialog box. After they have been added to the toolbar, ToolTips are available.

Message Reminder Viewer Dialog Box Options

Use this dialog box to view reminders you've set. You can select a way to view them (either View Reminders as They Expire, View All Message Reminders, View All Folder Reminders, View Message Reminders By Date, or View Folder Reminders By Date) by choosing a new filter.

When you choose View All Message or All Folder Reminders, double-click an item to read it. When you choose View All Messages or All Folder Reminders By Date, you can change the date from its default (the default is the current date).

When you work in the Reminder Viewer, you can use the following buttons:

Button | Description
Close | Closes the Reminder Viewer.
Open | Opens a message if a message reminder is selected
Properties | Opens the Set Reminder dialog box, where you can revise a reminder.
Disable | Maintains reminder information but doesn't display a reminder
Snooze | Delays the reminder according to the time you add using the Snooze dialog box.
Select All | Selects all messages and folders.
Delete | Deletes the selected reminders. Use the Delete button with care; there is no Undo option to recreate reminders that you delete.

Right-click on a message or folder in the Reminder Viewer to open a shortcut menu that displays the commands you can use with that message or folder.

Message Reminder Dialog Box Options

Option | Description
Disabled | Select to disable, but not lose, reminder information you set in the When and Occurs boxes. In the upper-right corner, check the information to verify that you've selected the number of messages or folders you want to set a reminder on.
When Box | Use this area to set up the reminder.
Remind at | You can type a time, such as 12:00 P.M., or set the time and date by using any one or all of the Time Remaining boxes.
On | Choose the > button to open the calendar if you want to change the day displayed in the On box. When you open the calendar, double-click the date you want. Use the buttons in the upper-right and upper-left corners of the calendar to move back or forward one month per click.
Time Remaining | You can use the Days, Hours, Minutes, and Seconds boxes to set a reminder. Otherwise, the boxes display the time remaining before the reminder appears.
Occurs | Use the features available in this area to set a recurring reminder for one of the following intervals: every 15 or 30 minutes, hourly, daily, weekly, monthly, yearly, or by the weekday. Select By Weekday to enable the days of the week check boxes. The default recurring reminder is None. Choose Save to save your reminder. Choose Viewer to open the Message Reminder Viewer.
.Dat Files | Two files, Reminder.dat and Buttons.dat, contain the dynamic data that is written when a user works withPreview Pane Extension. Buttons.dat contains all the button settings and customized options for a user; Reminder.dat contains all the reminders.


Microsoft Mail Export Tool

The Microsoft Mail Export tool (Eximwiz.exe) converts Microsoft Exchange Bulk Export format (.csv) files to Microsoft Mail import format. After creating the output file, you can use the tool to interactively import addresses into a Microsoft Mail postoffice on the network, or you can e-mail the import file to external recipients.

In addition, new functionality enables you to export from Microsoft Mail, and create a .csv file to add Microsoft Mail recipients as Microsoft Exchange custom recipients.

Eximwiz is useful when directory synchronization between a Microsoft Exchange Server implementation and Microsoft Mail is not a viable option (if, for example, you are trying to populate a trading partner's Microsoft Mail system with relevant addresses, such as purchasing agents, from your global address list). Eximwiz can also be used to manually perform directory synchronization between a Microsoft Exchange Server computer and a foreign mail switch that does not support the Microsoft Mail Dirsync protocol.

Note The Eximwiz tool supports the Windows 95 and Windows NT version 3.51 or later operating systems for x86 platforms only.


Installing Eximwiz

Installing the Eximwiz tool is a simple process. After installation, the Eximwiz tool is ready to use as a command-line utility.

To install the Eximwiz tool

From the Exchange\<operating system>\Admin\Eximwiz2 subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all files to your computer.

Copy Msmapi32.ocx to your system directory (C:\Windows\System on Windows 95 or C:\Windows\System32 on Windows NT).

At the command prompt, switch to the subdirectory that contains Eximwiz, then type Setup.exe.


Using Eximwiz

To use Eximwiz to convert Microsoft Exchange Bulk Export files to Microsoft Mail import format

Start the Microsoft Exchange Server Administrator program, and then export the addresses from the required container to a .csv file.

Run Eximwiz.exe.

Select the input file as the .csv file from the previous step, and then select an output file to which the Microsoft Mail import instructions will be written.

Select the user addresses that you want to process. If you want to process a majority of the addresses, select the Add All option and then remove the addresses that you don't want to process.

You will be prompted to select one of the following options:

  • Stop after creating the output file.
  • E-mail the file to a Microsoft Mail administrator.
  • Directly import this information into a Microsoft Mail postoffice on the network.

After you select the option you want, supply the appropriate information (postoffice name, administrator ID and password for Microsoft Mail directory import, and MAPI logon and recipient address information).

To use Eximwiz to export from Microsoft Mail, and create a .csv file to add Microsoft Mail recipients as Microsoft Exchange custom recipients.

Start the Microsoft Mail Import program, and then export the mailboxes from the required postoffice to a text file.

Run Eximwiz.exe.

Select the text file created by the Microsoft Mail Import program from the previous step, and then select an output file to which the data will be converted into an Exchange.csv input file

Select the mailboxes from the Microsoft Mail ASCII text file you want to process. If you want to process a majority of the mailboxes, select the Add All option and then remove the mailboxes that you don't want to process.

Choose either the Microsoft Mail friendly name in the "FirstName" format or the "LastName FirstName" format.

The following fields are filled with data in the .csv file. You can also select other fields to add to the.csv file.

  • Obj-Class
  • Alias name
  • Directory name
  • E-mail address

You will be prompted to select one of the following options:

  • Stop after creating the output file, or
  • E-mail the file to a Microsoft Exchange administrator.

Select the option you want, and then supply the appropriate information

After you save your selection, use Eximwiz later to add addresses to the .csv file as necessary. This feature prevents you from having to edit the ASCII file or make another connection to the Microsoft Mail postoffice for a new list.


Microsoft Mail Proxy to Microsoft Exchange Proxy Conversion Tool

This tool converts existing SMTP/MHS/X.400 addresses from a Microsoft Mail Export format to Microsoft Exchange Bulk Import format (.csv) so that they can be added as custom recipients to a Microsoft Exchange Server Recipient container.


Installing the Proxy Conversion Tool

The Microsoft Mail SMTP Gateway Proxy Migration tool (Perl.exe) is included on the Microsoft BackOffice Resource Kit, Part Two compact disc.

To install the Proxy Conversion tool

  • From the Exchange\Common\Proxy directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the following files to a directory of your choice.
    • Perl.exe
    • Perl100.dll
    • Convert.pl
    • Go.bat (Sample file optional)
    • In.txt (Sample file optional)
    • Out.txt (Sample file optional)
    • Fail.txt (Sample file optional)

For more information on the PERL program, see the Microsoft Windows NT Resource Kit version 3.51.


Using the Proxy Conversion Tool

Run Import.exe against an existing Microsoft Mail postoffice.

Type the following:

PERL <input_file > <output_file>

where input_file is the file created in step 1, and output_file is the .csv file for the conversions.

Using the Microsoft Exchange Server Administrator program, import the .csv file to add the addresses as custom recipients to a Microsoft Exchange Server Recipient container.

Sample Files

The following sample files are included on the compact disc:

  • In.txt (sample input file)
  • Go.bat (sample command file)
  • Out.txt (sample output file)
  • Fail.txt (sample error file)


Microsoft Mail Route Change Program

The Microsoft Mail Route Change Program enables a Microsoft Mail administrator to automatically change the routing of all external Microsoft Mail postoffices.

By using this tool, you can change the routing so that all external postoffices are defined as direct. You can also define postoffices as indirect through another postoffice (hub postoffice).


Installing the Microsoft Mail Route Change Program

To install the Chgroute.exe file

  • From the Exchange\<operating system\platform>\Admin\Chgroute subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Chgroute.exe to a directory on your computer.


Using the Microsoft Mail Route Change Program

The Microsoft Mail Route Change Program changes the connection of all external postoffices to a local area network (LAN). If certain postoffices need to be defined as using a modem or an X.25 connection, you must run the Microsoft Mail Admin.exe program and change the external postoffice configuration.

Before running the actual program, the Route Change program backs up the .xtn files to a Bak subdirectory in the Xtn subdirectory. The Network.glb file is also backed up to a Bak subdirectory in the Glb subdirectory.

In the event an error is encountered, the backed up files are restored before the program stops.

Command-Line Options

When running the Microsoft Mail Route Change Program, you can use the following command-line options.

CHGROUTE admin [-D<d|path>] [-L<log file>] -N<network> -O<postoffice> -P<password> [-V] [-Y] [-?]

Option | Description
admin | The mailbox assigned to the Microsoft Mail administrator.
-D<d | path> | Drive D specifies the mail data files drive (the default drive is M). Path specifies the path to the mail data files.
-L<log file> | The file to which logging information is written.
-N<network> | Specifies the network name of the new hub postoffice.
-O<postoffice> | Specifies the postoffice name of the new hub postoffice.
-P<password> | The mailbox logon password of a Microsoft Mail administrator.
-R<I | D> | Specifies the new routing of all external Microsoft Mail postoffices. I - Indirect routing. The –N and –O options are required D - Direct routing.
-V | Displays/logs detailed logging information.
-Y | Overrides the confirmation message.
-? | Displays this message.


Microsoft Mail SMTP Gateway Proxy Migration Tool

The Microsoft Mail SMTP Gateway Proxy Migration tool (Migsmtp.exe) helps replace a Microsoft Mail SMTP gateway with a Microsoft Exchange Internet Mail Service by reducing the level of administrator intervention. It preserves current Internet addresses of the recipients and adds them as secondary proxies to the Microsoft Exchange Server global address list, which eliminates the need for the end users to republish their new Internet address for their business associates. This tool is useful for the following scenarios:

Scenario | Action
Replace a single Microsoft Mail SMTP gateway and associated postoffice with Microsoft Exchange and the Internet Mail Service. | Migrate all users. Run Migsmtp.exe. Shut down the Microsoft Mail SMTP gateway and put its IP address on the Internet Mail Service computer.
Replace a Microsoft Mail SMTP gateway and networked postoffices with multiple Microsoft Exchange servers and the Internet Mail Service. | Migrate all users to servers. Visit each server and process recipients to assign proxies using Migsmtp.exe.
Replace a Microsoft Mail SMTP gateway with the Internet Mail Service and Microsoft Exchange Server. | Remaining postoffices are connected to Microsoft Exchange by using the Microsoft Mail Connector.
Replace a postoffice server. | Perform directory synchronization. Modify proxies by using Migsmtp.exe. When you migrate users to Microsoft Exchange Server, rerun Migsmtp.exe to modify existing proxy addresses. This ensures that users maintain the addressing attributes they had in Microsoft Mail.


Installing the Microsoft Mail SMTP Gateway Proxy Migration Tool

The Microsoft Mail SMTP Gateway Proxy Migration tool is included on the Microsoft BackOffice Resource Kit, Part Two compact disc.

To install the Microsoft Mail SMTP Gateway Proxy Migration tool

  • From the Exchange\<operating system\platform>\Migrate\Migsmtp directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Migsmtp.exe to a Microsoft Exchange Server computer.


Using the Microsoft Mail SMTP Gateway Proxy Migration Tool

To run the Microsoft Mail SMTP Gateway Proxy Migration Tool

  • Type the following at the command prompt:

    MIGSMTP [-?] [-R] [-V] [-Ccontainer] [-Taddresstype] -sserver -pPOpath

The following table lists the command-line options available, and their descriptions:

Option | Description
-? | Displays Help.
-R | Replaces the primary simple mail transfer protocol (SMTP) proxy name. If not specified, the Microsoft Mail SMTP proxy name is appended as a secondary SMTP proxy name.
-V | Verbose progress reporting.
-C | Processes only the recipients in container. If -C is not specified, only the Recipients container will be processed.
-T | Uses addresstype as the type of the generated address instead of SMTP.
-s | server is the name of the Microsoft Exchange Server computer to run the process on.
-p | POpath is the path to the MicrosoftMail postoffice. The Addrmap.cfg and Local.cfg files are required by the proxy generation process. These files must be located in the path specified either in a live database in the directory, or as separate files in the directory.

Migsmtp.exe adds an SMTP secondary proxy for the user that is located by converting the Microsoft Mail address (type MS in Microsoft Exchange Server). The Microsoft Mail address is searched for in the following order:

The target address in a custom recipient

The primary proxies

The secondary proxies

This transformation is not performed on custom recipients with a target address of type SMTP. Address generation for SMTP addresses also takes place for distribution lists and recipients hidden from the Address Book.


Microsoft Schedule+ Address Book Assistant

The Microsoft Schedule+ Address Book Assistant (the Assistant) is a Microsoft Visual Basic 4.0 32-bit application that copies Address Book entries into a Schedule+ contact list. This enables you to accomplish tasks that are not supported by the Address Book, such as printing contacts and adding contacts to watches that support Schedule+.


Installing the Assistant

To install the Assistant on Windows 95

  • Run Setup from the Exchange\<operating system\platform>\Client\Schedaba directory on the Microsoft BackOffice Resource Kit, Part Two compact disc.

To install the Assistant on non-Windows 95 operating systems

Copy Schedaba.exe to your Windows directory.

Copy all the dynamic-link libraries (DLLs) from Client\Schedaba to your Windows\System directory.

Run Schedaba.reg to add an entry for the tool to the registry.


Using the Assistant

To use the Assistant, start Schedule+, and then choose Import from the File menu. You can select Address Book entries from any Address Book, but the Assistant only ports individual user entries. Distribution lists are not supported.

When you select an Address Book entry to copy, the Address Book Assistant scans the schedule file to determine whether the entry already exists. If the entry exists, you are prompted to choose whether you want to update the entry. If the entry is not found, it is automatically created.

The Assistant can add and/or update the following Schedule+ fields:

  • FirstName
  • LastName
  • User1
  • User4
  • JobTitle
  • Company
  • PhoneBusiness
  • Office
  • PhonePager
  • PhoneMobile
  • Department

These fields are updated with the Address Book information (or left blank as necessary) with the following exceptions:

  • If first and last names aren't included in the Address Book, the DisplayName is used in the LastName field of the Schedule+ contact.
  • The User1 field contains the e-mail address.
  • The User4 field contains the string "Created by Microsoft Schedule+ Address Book Assistant" so that you can identify the entries created by the tool.
  • The Job Title through the Department fields are only changed if there is information in the Address Book for that entry.


Natural Language Support Configuration Tool

The Natural Language Support (NLS) Configuration tool automates the process of configuring a Microsoft Exchange Server computer to support a variety of languages. On a practical basis, it enables a Microsoft Exchange Server computer to support Microsoft Exchange Clients running on operating systems configured for different languages. The tool automates this process by installing code-page files for languages not supported by default in the Windows NT language list.

The NLS tool is also useful for those who want to manually install individual code pages on an as-needed basis for Windows, Microsoft Exchange-DOS and Apple Macintosh operating environments.


Installing the NLS Configuration Tool

To install the NLS Configuration tool

  • From the Exchange\Common\NLS subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Nls.exe to your computer.


Before Using the NLS Configuration Tool

Before using this tool, you must log on to an account with administrator rights, then follow the steps below.

At the command prompt, switch to the directory containing the Setupnls.bat file, and then type: Setupnls

This command updates a variety of NLS files in your System32 directory and writes a Setupnls.log file to your Temp directory. You can review this file before proceeding further.

Reboot your computer so that Windows NT Server can update the files. This also makes the outdated files available so that they can be deleted by Cleannls.

At the command prompt, switch to the directory containing the Cleannls.bat file, and then type: CLEANNLS

This deletes the outdated NLS files from your SYSTEM32 directory.

Note Correct Korean sorting requires either the Korean version of Windows NT Server version 3.51, or any language version of Windows NT Server version 4.0 or later.


Using the NLS Configuration Tool

The Nls.exe file adds code pages for languages that need to be installed on a Microsoft Exchange Server computer. If the code pages used by the client operating system have not been installed on the Microsoft Exchange Server computer, the client receives the following error message: "The Microsoft Exchange Server computer is not configured to support your code page, and can't log on to the Microsoft Exchange Server."

Manually Adding Code-Page Files

Before you select a new language, you must manually add code-page files.

To manually add code-page files to your computer

Copy the code-page file you want to add to the %systemroot%\system32 directory. Use the following file name format: C_<ANSI code page ID>.NLS.

For example: C_950.NLS.

From the Start menu, choose Run, and then select Regedt32.exe.

Add a value under the following registry key:

\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Nls\
CodePage.

To add a value in the registry key, select a value from those listed in the following table.

Value | Description
Value Name | The ANSI code page ID
Data Type | REG_SZ
String | The file name of the code-page file

Add a value under the following registry key:

\\HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Nls\
Language

To add a value in the registry key, select a value from those listed in the following table.

Value | Description
Value Name | The Microsoft Windows Locale ID
Data Type | REG_SZ
String | 1_intl.nls

Internationalization Features

Windows NT Server includes two internationalization features that are used by Microsoft Exchange Server:

  • Sorting according to the client language.
  • Converting data between the client code page and Unicode.

Both features are supported by the NLS components in Windows NT Server. The NLS tool offers a core set of services for applications to use. Additional languages can be supported by adding .NLS data files.

This tool updates the .NLS data files on your Windows NT Server to add support for a wide variety of American, European, and Asian locales and code pages.

Code Pages

Microsoft Exchange Server uses Unicode to mediate between different code pages that can be used by Microsoft Exchange Clients.

C_nnn.nls files are added to support conversion between code page "nnn" and Unicode. Note that the code page used by a client (for example, an English code page) is not directly tied to the translation of the Microsoft Exchange Client. Instead, the Microsoft Exchange Client (of any language) consults the operating system it is running to determine the code page. For example, an English client running the Russian version of Windows uses the Russian code page (code page 1251). Adding C_1251.nls on the Windows NT Server enables Microsoft Exchange Clients running the Russian version of Windows to log on.

Locales

Microsoft Exchange Server can sort lists (for example, addresses and messages) according to the locale of the client viewing the list. Locales are characterized by a major language and a sub-language or location.

The following core files contain support for sorting and are updated by this tool (or are added if they do not already exist in your version of Windows NT Server): Sortbls.nls, Sortkey.nls, Prc.nls, Prcp.nls, Xjis.nls, Big5.nls.

Code-Page List

The following lists identify the code pages installed by the NLS Configuration tool.

Windows Code Pages

874 Thai - ANSI, OEM

932 Japanese - ANSI, OEM

936 Chinese GBK (PRC, Singapore) - ANSI, OEM

949 Korean Extended Wansung - ANSI, OEM

950 Chinese BIG5 (Taiwan Region, Hong Kong SAR, PRC) - ANSI, OEM

1250 Central / Eastern Europe - ANSI

1251 Cyrillic - ANSI

1252 Latin I - ANSI

1253 Greek - ANSI

1254 Turkish - ANSI

1255 Hebrew - ANSI

1256 Arabic - ANSI

1257 Baltic - ANSI

1258 Vietnam - ANSI, OEM

OEM Code Pages

437 United States - OEM

737 Greek (aka 437G) - OEM

775 Baltic - OEM

850 Multilingual (Latin I) - OEM

852 Slovak (Latin II) - OEM

855 Cyrillic - OEM

857 Turkish - OEM

860 Portuguese - OEM

861 Icelandic - OEM

862 Hebrew - OEM

863 Canadian French - OEM

864 Arabic - OEM

865 Nordic - OEM

866 Russian - OEM

869 Modern Greek - OEM

Apple Macintosh Code Pages

10000 Roman - MAC

10001 Japanese - MAC

10006 Greek I - MAC

10007 Cyrillic - MAC

10010 Romania - MAC

10017 Ukraine - MAC

10029 Latin II - MAC

10079 Icelandic - MAC

10081 Turkish - MAC

10082 Croatian - MAC

Locales List

The following list shows the local ID code for each locale.

Locale ID | Locale
0401 | Arabic - Saudi Arabia
0801 | Arabic - Iraq
0c01 | Arabic - Egypt
1001 | Arabic - Libya
1401 | Arabic - Algeria
1801 | Arabic - Morocco
1c01 | Arabic - Tunisia
2001 | Arabic - Oman
2401 | Arabic - Yemen
2801 | Arabic - Syria
2c01 | Arabic - Jordan
3001 | Arabic - Lebanon
3401 | Arabic - Kuwait
3801 | Arabic - U.A.E.
3c01 | Arabic - Bahrain
4001 | Arabic - Qatar
0402 | Bulgarian - Bulgaria
0403 | Catalan - Spain
0404 | Chinese - Taiwan
0804 | Chinese - PRC
0c04 | Chinese - Hong Kong
1004 | Chinese - Singapore
0405 | Czech - Czech Republic
0406 | Danish - Denmark
0407 | German - Germany
0807 | German - Switzerland
0c07 | German - Austria
1007 | German - Luxembourg
1407 | German - Liechtenstein
0408 | Greek - Greece
0409 | English - United States
0809 | English - United Kingdom
0c09 | English - Australia
1009 | English - Canada
1409 | English - New Zealand
1809 | English - Ireland
1c09 | English - South Africa
2009 | English - Jamaica
2409 | English - Caribbean
2809 | English - Belize
2c09 | English - Trinidad
040a | Spanish - Spain (Traditional Sort)
080a | Spanish - Mexico
0c0a | Spanish - Spain (Modern Sort)
100a | Spanish - Guatemala
140a | Spanish - Costa Rica
180a | Spanish - Panama
1c0a | Spanish - Dominican Republic
200a | Spanish - Venezuela
240a | Spanish - Colombia
280a | Spanish - Peru
2c0a | Spanish - Argentina
300a | Spanish - Ecuador
340a | Spanish - Chile
380a | Spanish - Uruguay
3c0a | Spanish - Paraguay
400a | Spanish - Bolivia
440a | Spanish - El Salvador
480a | Spanish - Honduras
4c0a | Spanish - Nicaragua
500a | Spanish - Puerto Rico
040b | Finnish - Finland
040c | French - France
080c | French - Belgium
0c0c | French - Canada
100c | French - Switzerland
140c | French - Luxembourg
040d | Hebrew - Israel
040e | Hungarian - Hungary
040f | Icelandic - Iceland
0410 | Italian - Italy
0810 | Italian - Switzerland
0411 | Japanese - Japan
0412 | Korean - Korea
0413 | Dutch - Netherlands
0813 | Dutch - Belgium
0414 | Norwegian - Norway (Bokmal)
0814 | Norwegian - Norway (Nynorsk)
0415 | Polish - Poland
0416 | Portuguese - Brazil
0816 | Portuguese - Portugal
0418 | Romanian - Romania
0419 | Russian - Russia
041a | Croatian - Croatia
081a | Serbian - Serbia (Latin)
0c1a | Serbian - Serbia (Cyrillic)
041b | Slovak - Slovakia
041c | Albanian - Albania
041d | Swedish - Sweden
081d | Swedish - Finland
041e | Thai - Thailand
041f | Turkish - Turkey
0421 | Indonesian - Indonesia
0422 | Ukrainian - Ukraine
0423 | Belarussian - Belarus
0424 | Slovene - Slovenia
0425 | Estonian - Estonia
0426 | Latvian - Latvia
0427 | Lithuanian - Lithuania
0429 | Farsi - Iran
042a | Vietnamese - Vietnam
042d | Basque - Spain
0436 | Afrikaans - South Africa
0438 | Faeroese - Faeroe Islands

Selecting a New Language

To select a new language

From the Windows NT Server Start menu, choose Settings.

Choose Control Panel, double-click the International icon, and then select a language.

The following table lists languages that Microsoft currently supports:

Language | ANSI Code Page ID | Code Page NLS Files | Language Code Page ID
Czech | 1250 | c_852.nls | 0405
Danish | 1252 | c_850.nls | 0406
Dutch | 1252 | c_850.nls | 0413
English (Australia) | 1252 | c_850.nls | 0C09
English (Britain) | 1252 | c_850.nls | 0809
English (Canada) | 1252 | c_850.nls | 1009
English (Ireland) | 1252 | c_850.nls | 1809
English (New Zealand) | 1252 | c_850.nls | 1409
English (South Africa) | 1252 | c_437.nls | 1C09
English (US) | 1252 | c_437.nls | 0409
Finnish | 1252 | c_850.nls | 040B
French | 1252 | c_850.nls | 040C
German | 1252 | c_850.nls | 0407
Greek | 1253 | c_737.nls | 0408
Hungarian | 1250 | c_852.nls | 040E
Italian | 1252 | c_850.nls | 0410
Norwegian | 1252 | c_850.nls | 0814
Polish | 1250 | c_852.nls | 0415
Portuguese (Portugal) | 1252 | c_850.nls | 0816
Portuguese (Brazil) | 1252 | c_850.nls | 0416
Russian | 1251 | c_866.nls | 0419
Spanish (Mexico) | 1252 | c_850.nls | 080A
Spanish (Modern Sort) | 1252 | c_850.nls | 0C0A
Spanish (Traditional Sort) | 1252 | c_850.nls | 040A
Swedish | 1252 | c_850.nls | 041D
Turkey | 1254 | c_857.nls | 041F
Japanese | 932 | c_932.nls | 0411
Korean | 949 | c_949.nls | 0412
Chinese (PRC) | 936 | c_936.nls | 0804
Chinese (Taiwan) | 950 | c_950.nls | 0404


ONDL Tool

The ONDL tool is a Microsoft Win32® command-line utility that displays the members of a Microsoft Exchange Server distribution list (DL). This tool can also display the Microsoft Exchange distribution lists that a user is a member of.

The ONDL tool is designed for the following operating systems:

  • Microsoft Windows 95
  • Windows NT version 3.51 and later


Installing ONDL

Before installing ONDL, make sure that you have the Microsoft Exchange Client installed.

To install the Ondl.exe file

  • From the Exchange\<operating system\platform>\Admin\OnDL subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Ondl.exe to a directory on your computer.


Using ONDL

You can run the ONDL tool from the command line with any combination of the following switches, and an alias name. Following is typical syntax usage for the ONDL tool.

ONDL [/A] [/H | /?] [/M] [/Q] [/S] [/V] AliasName

Syntax | Description
/A | Modifier switch. If used, output includes only the alias name of any recipients displayed. Default format is: AliasName, DisplayName.
/H | /? | Displays the Help screen.
/M | Modifier switch. If used, AliasName is interpreted to be a message recipient, and all of the DLs that AliasName is a member of are displayed.
/P | Profile Use MAPI profile with the name "Profile." If the profile name contains spaces, it must be enclosed in double quotes.
/Q | Quiet mode. Informational headers and footers are suppressed. Only member or member of output is displayed.
/R | Recursively expands membership list of nested DLs. This switch is ignored if used with output modifier switches /A, /M, or /S.
/S | Alias stream mode. Output is a continuous stream of semi-colon delimited alias names. Implies /A switch behavior.
/U | Use different MAPI profile. Do not piggy-back on an existing session, but instead prompt for a profile to use.
/V | Verbose output. Displays all diagnostic output.
AliasName | The target alias name for the DS query. Normally considered to be the alias name of the distribution list whose membership is to be displayed. Behavior is changed by use of the /M switch.

Searches are performed only against a Microsoft Exchange Server global address list (GAL). Personal Address Book (PAB) searches are not supported. The ONDL tool piggy-backs on the existing MAPI session, if one has already been established. Otherwise, the standard MAPI logon prompt is displayed.

Normal output is sent to stdout (standard output), with error messages going to stderr (standard error).

ONDL Syntax and Output Samples

Below are examples of ONDL syntax and output:

ONDL dlalias

Displays the members of the distribution list "dlalias" in "AliasName, DisplayName" format.

ONDL /Q dlalias

Quiet mode. Same as above, but suppresses the display of the informational header and footer text. Useful when you just want member/member of data.

ONDL /M myalias

Displays the distribution lists that "myalias" is a member of in "AliasName, DisplayName" format.

ONDL /A dlalias

Displays only the AliasName of members of the distribution list "dlalias," one to a line.

ONDL /S /M myalias

Produces a stream of semi-colon delimited AliasNames that are distribution lists that "myalias" is a member of. This output is suitable for copying to the Windows Clipboard and pasting to the To: line of a message. However, if you copy the text directly from the command prompt window, the Clipboard manager (on Windows NT 3.51) inserts end-of-line carriage returns where there are none. So when you paste to the To: line, you must remove any inserted line breaks. You can avoid this problem by redirecting output to a file and then using a text editor such as Notepad to copy and paste the output.


PFAdmin Tools

The PFAdmin tools have been expanded to include reporting capabilities for interpersonal message (IPM) types within the entire public folder tree, single folder, or subtree. The report is provided as a .csv file that includes headings to describe the IPM type.

PFAdmin is actually comprised of three separate tools:

  • Public Folder ACL Replication tool
  • Re-Home Public Folder tool
  • Public Folder Item Type tool


Installing the PFAdmin Tools

To install the PFAdmin tools

From the Exchange\<operating system\platform>\PfTools\PfAdmin subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy PFAdmin.exe to your computer.

Copy aclcls.dll to your System32 directory.


Using the PFAdmin Tools

You can use the following command-line syntax format when running PFAdmin:

  • PFADMIN [Switches] Profile SETACL Folder|ALL User Rights [User Rights]... [YES|NO]
  • PFADMIN [Switches] Profile REHOME Folder|ALL [Site\]Server [YES|NO]
  • PFADMIN [Switches] Profile SETREPLICAS Folder Option Server(s)
  • PFADMIN [Switches] Profile LISTACL Folder|ALL [YES|NO]
  • PFADMIN [Switches] Profile LISTREPLICAS Folder|ALL [YES|NO]
  • PFADMIN [Switches] Profile MESSAGETYPES Folder|ALL [FULL|I=IniFile] [O=CsvFile]

Following is a list of the command-line switches available in PFAdmin:

  • /En = eventlog logging level (default = 3)
  • /Cn = console logging level (default = 4)
  • /Dn = debug file logging level (default = 5)
  • /Ln = logging level (console, debug, and EventLog)

    where 0=NONE, 1=STATUS, 2=ERROR, 3=WARNING, 4=INFO, 5=DEBUG

Logging Level Defaults

Logging levels range from 0 to 5, with Level 5 being the highest level.

  • Level 3 — Output to the EventLog.
  • Level 4 — Output to stdout.
  • Level 5 — Output to the log file.

PFAdmin and Message Types

PFAdmin can search a specified folder tree, examine the message type of every message, and then write a .csv file that contains one line for each folder examined.

To search a specified folder tree and write a .csv file

  • At the command prompt, type:

    >pfadmin ? messagetypes):

Sample .csf File Format and Syntax

The PFAdmin tool enables you to configure the IPM types you want to monitor. The message types are provided within the Default.ini file. A single level of subtypes is allowed. Messages that fall within a subtype are counted in both the subtype and its parent type.

Following is a sample .csv file format listing. The numbers in this example were chosen arbitrarily:

FOLDER,ITEMS,IPM_Type1,IPM_Type2, IPM_Type3,…
Folder One,99,16,3,967,...
Folder One\Subfolder A,16,0,2,222,...
TOTALS,9999,111,44,888...

ITEMS represents the total number of messages in the folder (note that only HOMED messages are counted if this option is enabled). The remaining fields represent the number of messages for each message type found in the folder. Note that PFAdmin does not examine attachments and objects within these messages.

For the default and I=IniFile option, a message type is considered to match a default (or .ini-specified) type if the left-most characters match. Any additional characters are ignored. All other message types are combined into the All Other category. For the Full option, all characters are used to match message types and all types found are reported.

Help Syntax

To get Help when using PFAdmin

At the command prompt, type:

pfadmin ?

For additional Help, type any of the following commands:

  • PFADMIN ? SETACL
  • PFADMIN ? REHOME
  • PFADMIN ? SETREPLICAS
  • PFADMIN ? LISTACL
  • PFADMIN ? LISTREPLICAS
  • PFADMIN ? MESSAGETYPES

Notes On Using the PFAdmin Tools

  • All entries are case-insensitive.
  • You must use quotation marks when typing names containing blanks and use backslashes when typing subfolder names, starting with the top-level folder under All Public Folders.
  • You can specify user rights by typing either a full name or character(s). You can combine rights by using the '|' symbol [for example, read | write (blanks optional)] or joining characters into a single word (for example, RW).
  • You can also use "Default" as the user name to set the default permissions.

Examples of Command-Line Syntax

Following are examples of typical syntax usage for the PFAdmin Tools:

  • >pfadmin <profile> setacl all "pf global admin" owner "pf lead" o
  • >pfadmin <profile> setacl "Readme FAQ\Exchange Discussion" UserName r
  • >pfadmin <profile> setacl all default read


PFTreeInfo Tool

The PFTreeInfo tool counts all the messages in a selected folder and all its subfolders. This tool is very useful for verifying folder replication, especially for the Microsoft Exchange Internet News Service, which contains a large collection of folders and messages.


Installing PFTreeInfo

To install the PFTreeInfo tool

  • From the Exchange\<operating system\platform>\PfTools\PFtree subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all files to your computer.


Using PFTreeInfo

Note that this tool is designed for the Microsoft Win32 environment only.

The following is a list of functions performed by the PFTreeInfo tool.

  • Specifies a profile to log on to.
  • Uses the tree control to step down the folder's subfolders and choose any folder to be counted.
  • Counts all the messages, or subfolders, or both.
  • Starts the counting process when you choose the Start Count button.
  • Indicates that the counting process is running by showing a ticking clock.
  • Updates the counting result every half-second.
  • Stops the counting process at any time when you choose the Stop Count button.
  • Adds all the folders that you access to the list box.


Using PFTreeInfo

You can perform the following tasks by using PFTreeInfo:

  • Count messages recursively.
  • Count subfolders recursively.
  • Count messages and subfolders recursively.

The following figure illustrates the PFTreeInfo user interface.

To count messages recursively

Select the Count messages check box.

Choose Start Count.

To count subfolders recursively

Select the Count sub folders check box.

Choose Start Count.

To count messages and subfolders recursively

Select the Count messages and Count sub folders check boxes.

Choose Start Count.


Phone Book Search Tool

The Phone Book Search tool enables you to search through a list of recipients to locate a Microsoft Exchange user. You can use this tool when you know only the user's e-mail alias or phone number.


Installing the Phone Book Search Tool

To install the Phone Book Search tool

  • From the Exchange\<operating system\platform>\Admin\Phone directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Phone.exe and Wldap32.dll to your computer.


Using the Phone Book Search Tool

The following procedures outline how to perform specific functions with the Phone Book Search tool, including:

  • Searching by e-mail alias
  • Searching by phone number

Note Microsoft Exchange Server computers do not have an index for phone numbers; therefore this search could be time-consuming. Adding an index on the phone number attribute speeds up this task.

To search by e-mail alias

At the command prompt, switch to the directory where Phone.exe is installed.

Type Phone <Microsoft Exchange Server computer name> <e-mail alias> (for example, Phone exchange1 adelew).

You can also use wildcards to search for multiple phone numbers (for example, Phone exchange1 adelew*).

To search by phone number

At the command prompt, switch to the directory where Phone.exe is installed.

Type Phone <Microsoft Exchange Server computer name> <phone number>.


PKicker Tool

PKicker is an abbreviation for Proxy Kicker. PKicker is a command-line tool that can add, update, and delete proxies on local and remote servers.


Installing PKicker

To install the PKicker tool

  • From the <operating system\platform>\Admin\Pkicker subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Pkicker.exe and Rpcdce4.dll to your computer.


Using PKicker

When a proxy is added or updated, only mailboxes that currently have a proxy of that type are updated. The only way to complete this task is to export all the recipients and then import them back in. The PKicker tool enables a user to add a new proxy and then force all the mailboxes to be updated. PKicker can also delete proxies, thus removing the specified proxy from all your mailboxes, not custom recipients.

To run the Pkicker tool

  • Use the following command-line syntax

    PKicker /T<proxy type> [/S<server>] [/F<n>]

The following table lists the command-line options available in PKicker, and their descriptions:

Parameter | Description
/S | Server name. (default: local server)
/T | Type of connector, for example Lotus cc:Mail.
/F | Desired action. The default is ADD where ADD is // Add new proxy to all users, DEL is // Del a current proxy and UPD is // Update the proxy.

Performing Specific Functions with PKicker

The following procedures outline how to use the PKicker tool to perform specific functions:

To access the Help menu

  • At the command prompt, type:

    pkicker /?

To add a Lotus cc:Mail proxy on the current Microsoft Exchange Server computer

  • At the command prompt, type:

    pkicker /TCCMAIL /FADD

To update a Lotus cc:Mail proxy on another server

  • At the command prompt, type:

    pkicker /TCCMAIL /SOtherServer /FUPD

To delete a Lotus cc:Mail proxy on another server

  • At the command prompt, type:

    pkicker /TCCMAIL /SOtherServer /FDEL


Profgen Tool

The Profgen tool is also known as the Automatic Profile Generator (Newprof.exe). The format of the Profile Descriptor File (.prf) is used with the Profgen tool. This file contains profile settings that Newprof.exe reads. These settings are added to the newly created profile.


Installing Profgen

To install the Profgen tool

  • From the Exchange\<operating system\platform>\Admin\Profgen subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Newprof.exe to your computer.

    Note Before installing Profgen, it is recommended that you read the installation section below that applies to your operating system ("Installing Profgen for Microsoft Windows NT," "Installing Profgen for Windows 95," or "Installing Profgen for Windows 3.x").


Installing Profgen for Microsoft Windows NT

To install Profgen for Windows NT

  • Add the following line to the Windows NT domain logon script:

    \\Server Name\Share Name\Profgen.exe C:\EXCHANGE\Newprof.exe
    -P H:\Winnt.prf

    where H:\ is the user's home directory.

    (This assumes that Newprof.exe is present in the C:\Exchange directory. You can also find Profgen.exe on your local hard disk instead of on the server.)


Installing Profgen for Windows 95

To install Profgen for Windows 95

Copy Profgen.exe to C:\Exchange.

Copy the Profgen.ini file to C:\Windows.

In the Profgen.ini file, edit the PathToExeFile and PathToPRFFile entries to point to the Newprof.exe and .prf files, respectively.

Normally these entries are: PathToExeFile=c:\exchange\newprof.exe PathToPRFFile=H:\Win95.prf where h:\ is the user's home directory on the server.

Edit the Load= line in the Win.ini file as follows. Load=c:\exchange\profgen.exe


Installing Profgen for Windows 3.x

To install Profgen for Windows 3.x

Copy the Profgen.ini file to C:\Windows.

In the Profgen.ini file, edit the PathToExeFile and PathToPRFFile to point to the Newprof.exe and .prf files respectively.

Normally these entries should be:

PathToExeFile=c:\exchange\newprof.exe PathToPRFFile=H:\Win16.prf

where h:\ is the user's home directory on the server, and c:\Exchange is the directory where the Microsoft Exchange Client is installed.

Edit the Load= line in the Win.ini file as follows:

Load=c:\exchange\profgen.exe

In the Win.ini file, make sure that the following line is present:

[MAPI] ProfileDirectory16=h: where h: is the home directory.


Using Profgen

Profgen simplifies the creation of Microsoft Exchange profiles for roving users. Users can move to any computer across operating systems and still access their Microsoft Exchange mailbox by double-clicking the Microsoft Exchange Client icon. Profiles do not have to be recreated.

Each of the Microsoft Exchange Clients share points contain a template .prf file (Template.prf). When the Microsoft Exchange Setup Editor is run against the client share point, it copies Template.prf to Default.prf. Any user option changes made by using the Setup Editor are then written to Default.prf. When the client Setup program is run, if the file Default.prf is present in the client installation directory, it is copied to the Windows directory on the client computer, and then Newprof.exe is run to create a new profile.

To run Profgen

In Windows Explorer, find the subdirectory where the Newprof.gen file is located.

Double-click Newprof.exe.

Profile Descriptor File

The Profile Descriptor File contains information relating to the services to be installed in the profile. This file contains four major sections:

  • Profile defaults
  • Services in the profile
  • Default values for each service
  • Mapping for profile properties
Profile defaults

This part of the .prf file contains values that apply to the entire profile specified in the [General] section. Under the [General] section, the following entries are used:

  • ProfileName=<Name of the Profile> — This entry specifies the name to be used when creating the profile.
  • DefaultProfile= [Yes/No] — If the value is set to Yes, then the profile being created is set as the default profile. By default, this entry is set to Yes.
  • OverwriteProfile= [Yes/No] — Determines whether the profile being created should overwrite an existing profile with the same name. If the value is set to No, and a profile exists with the same name as the one specified in the ProfileName entry, then the profile is not created. The default value is No.
  • DefaultStore=<Service ID> — Corresponds to a service that is to be used as the default store. The Service IDs are obtained from the entries listed in the [Service List] section as described below. By default, the value is set to Service2, which corresponds to the Microsoft Exchange Server service. This is determined by searching the [Service List] section. In that section, search for an entry whose name is Service2. The value of this entry is the actual name of the service.
Services in the profile

This part of the file lists all the services that are to be installed in the profile. The names of the profiles are listed as entries under the [Service List] section. By default, the [Service List] section is defined as shown below:

[Service List]

  • Service1=Microsoft Exchange Client
  • Service2=Microsoft Exchange Server
  • Service3=Personal Address Book

The services listed in this section are installed only if the settings associated with each of these services are valid. If the Automatic Profile Generator encounters a problem with one or more of the settings associated with a service, it will not install that service in the profile.

Default values for each service

This section of the file contains information for the services listed under the [Service List] section. For each of the services listed under the [Service List] section, there should be a section with that service name containing entries for each configurable option of the service.

By default, these are the service sections:

  • [Service1] — This section contains configurable options for the Microsoft Exchange Client. The different settings available in the Microsoft Exchange Client are included in Section 4 of the .prf file, which is described below.
  • [Service2] — This section contains settings for the Microsoft Exchange Server service. The different configurable settings available in the Microsoft Exchange Server service are included in Section 4 of the .prf file.
  • [Service3] — This section contains settings for the Microsoft Exchange Personal Address Book (PAB) service. The various configurable settings available in the Microsoft Exchange PAB service are included in Section 4 of the .prf file.
Mapping for profile properties

This section of the file contains a listing of all the supported properties for each of the services that the Automatic Profile Generator supports. For each service, there is a Section 4 with the name of the service. This section contains all the settings for the service that the Profile Generator supports. By default, there are sections for

  • Microsoft Exchange Client
  • Microsoft Exchange Server
  • Personal Folders
  • Personal Address Book
  • Microsoft Mail

For each entry in the [Service List] section, there must be a corresponding section in Section 4 of the file. For example, if under the [Service List] section, there is a Service1=Microsoft Exchange Client entry, there must be a [Microsoft Exchange Client] section in Section 4 of the file. The [Microsoft Exchange Client] section contains descriptions of all the options that can be set for the Microsoft Exchange Client. Each description contains the type of entry and an internal ID number. A text description of the entry explains the use of that option and the values that can be assigned to the option.

Newprof.exe reads Section 4 to determine how to interpret each of the options. The textual description of each option is commented out and Newprof.exe ignores these lines.

Using the above example, if there is a "Service1=Microsoft Exchange Client" entry in the [Service List] section, there should be a [Service1] section in Section 3 of the file, and a [Microsoft Exchange Client] section in Section 4.

For each entry specified in the [Service1] section, there must be a corresponding entry in the [Microsoft Exchange Client] section that describes the type (whether the option is a Boolean variable, integer, and so on) and an internal ID number. If the corresponding entry is not present in the [Microsoft Exchange Client] section, the Automatic Profile Generator cannot interpret that option and displays an error message.

To have Newprof.exe set a particular option for a service, the option must be listed with a valid value in the [Service ID] section, where Service ID is the entry name corresponding to that service in the [Service List] section. There must also be a section corresponding to the Service Name in Section 4 of the file, and this section should include the description information for the option that you need to set.


Roving User Profile Generation Program

The Microsoft Exchange Roving User Profile Generation Program (Profgen.exe) is a program that simplifies the creation of Microsoft Exchange profiles. It works in conjunction with the Automatic Profile Generator program (Newprof.exe) to create profiles.

Using the Roving User Profile Generation Program

To run Profgen

  • Use the following command-line syntax:

    Profgen.exe <path>\Newprof.exe -P <path>\Default.Prf [-S] [-X] [-L] [-U]

    The following table lists the command-line options available in Profgen, and their descriptions:

Option | Description
<path>\Newprof.exe | The name of the Newprof.exe file with the complete path.
-P <path>\Default.prf | The name of the .prf file to be used.
-S | Displays Newprof.exe with the -S option.
-X | Displays Newprof.exe with the -X option.
-L | Creates a log file (C:\Profgen.log).
-U | Updates the MailboxName= entry in the .prf file specified with the -P option, even if it already contains a value. By default, if the entry contains a value, it will not be updated and that value will be used.

Profgen.exe performs the following tasks:

Verifies whether the .prf file specified with the -P option is present. If it is not present, the program stops.

If the .prf file is present and accessible, the program obtains the currently logged-on Windows NT domain logon ID.

It then modifies the MailboxName= entry in the [Service2] section of the .prf file specified with the -P command-line option, by adding the currently logged-on user ID as the value of the MailboxName= entry.

If the -U option is not used, and the MailboxName= entry already contains a value, then the MailboxName= entry will not be modified with the current logon ID.

The modified .prf file is then copied to a temp file called C:\Profgen.tmp.

The program uses the following command:

<path>Newprof.exe -P C:\Profgen.tmp [-S] [-X].

Note The -S and -X options are only added to the command line for Newprof.exe if they were specified on the Profgen.exe command line or in the Profgen.ini file. The Profgen.ini file is described below.

Setting up roving users across platforms

You can enable Microsoft Exchange users to work from any computer and access their mailbox, regardless of their operating system (be it Windows NT, Windows 95, or Windows 3.x). You should not have to create a Microsoft Exchange profile on any of the computers used to access a Microsoft Exchange mailbox.

To set up roving users

Set up the operating system to allow for roving users.

  • For Windows NT, create a User Profile for each user, by using User Manager for Domains.
  • For Windows 95, you must enable User Profiles on each computer. From Control Panel, choose Passwords, then User Profiles.
  • For Windows 3.x, add the ProfileDirectory16= line to the [MAPI] section of the Win.ini file.

Assign Windows NT Domain logon scripts for each domain user.

For each user, create a home directory using User Manager for Domains, or the logon script.

Copy three .prf files in each user's home directory: one for each platform (WinNT, Win95 and Win16). For example, Win95.prf, Winnt.prf, and Win16.prf.

Creating a .prf file

To create a .prf file, run the Microsoft Exchange Setup Editor from any client installation point. Make sure that the Home Server field is entered on the Home Server tab of the User Options property page. This creates a file called Default.prf in the client installation directory. This file can be copied to Win95.prf, Winnt.prf and Win16.prf. These .prf files can be identical, and must contain all the information to be added to the user profile, except the MailboxName field. This is automatically entered by the Profgen.exe program.

You can move computers on different platforms, and the profile will be automatically created for the user, without any user intervention. The profile will be created the first time the user logs on, regardless of the platform. The profile should be saved in the user's home directory so that it is available the next time the user logs on to a computer with the same operating system.Note that you cannot set up roving users with the MS–DOS client. Microsoft Exchange user profiles for this environment must be manually created.

Roving Users with Windows NT Mandatory Profiles

With Mandatory Profiles, no changes to the Windows NT user profile are saved. Each time a user logs on, the default Windows NT profile overwrites the local Windows NT profile. The Microsoft Exchange profiles created during one Windows NT logon session are available the next time the user logs on. This problem can be resolved by using Profgen.exe to automatically recreate the user's Microsoft Exchange profile each time he or she logs on to the Windows NT Domain.

Creating roving users with Mandatory Profiles

To set up roving users with a mandatory profile

Modify the Windows NT logon script to copy a .prf file into the user's home directory.

Copy \\<Server Name>\<Share>\Default.prf H:\Winnt.prf

where H:\ is the user's home directory.

The program renames the .prf specified. The renamed file has the same name as the original .prf file specified, except that the last character of the file name is changed to ~. This prevents the program from trying to recreate a profile the next time it is run with the same command-line options.

Note Automatic creation of profiles for roving users with Profgen.exe works only if the user's Microsoft Exchange mailbox has the same name as his or her Windows NT Domain logon ID.

Using Profgen.ini

If no command-line options are specified, Profgen.exe searches for a file called Profgen.ini and reads data from that file. Following are the .ini settings for this file:

  • [NEWPROF] — Provides the path to the Newprof.exe file. The entry should read:

    PathToExeFile=c:\exchange\win95\newprof.exe

    You need to provide the path to the .prf file to be used to create the profile. If this entry is empty, the program searches for the Default.prf file in the Windows directory:

    PathToPRFFile= c:\default.prf

    If a file is specified, and this file does not exist, the program will stop and no profile will be created.

  • [PROFGEN] — If this entry is set to 1, a log called Profgen.log is created in drive C.
  • Logging=1 — If this entry is set to 1, the program will not update the MailboxName= entry in the .prf file with the current Windows NT logon ID. This entry will work only if the MailboxName= entry in the .prf file is not missing or blank.
  • UpdateMailboxName=1 — If this entry is set to 1, the mailbox name is updated.

Preventing Roving Users from Creating Local .Pst Files

To prevent users from being able to create personal folders, you can install the client on the computer without the Personal Folders service. Without this service, users will not be able to add personal folders to their Microsoft Exchange profile.

To install the client without the Personal Folders service

Run the Microsoft Exchange Setup Editor against a client installation share point.

From the File menu, choose Select Client Installation Point.

Select the Services tab.

Select the Personal Folders service from the To be installed on the client list, and then choose Remove.

Choose OK to quit the program.

Run the client Setup.exe program from the modified installation share point. The client installed will not have the Personal Folders service available.

Note that the above steps will work only if the client has never been installed on the computer in question. If the client was previously installed on the computer with the Personal Folders service, that service will be available even if the client was removed by selecting the Remove All option of the client setup program.

This is because the Personal Folders service is added to the Mapisvc.inf file in the Windows\System subdirectory. Even if the client is removed from the computer, the entry in the Mapisvc.inf file is not removed. Reinstalling the client with a different set of services only adds the new services to the Mapisvc.inf file; it does not remove any services from the .inf file. This is by design. With Windows 95, the Inbox client has many services that are not available with the Microsoft Exchange Server product. This includes the Internet Mail service, the Microsoft Network service and the Fax service. To prevent these services from being lost when upgrading to the full retail Microsoft Exchange Client, the client setup does not remove any services from the local computer.

The workaround to this problem is to manually edit the Mapisvc.inf file.

To manually edit Mapisvc.inf

  • Remove the following line from the [Services] section of the file:

    MSPST MS=Personal Folders

    Now when users choose Tools, Services, Add from the Microsoft Exchange Client, the Personal Folders service will not be available.


Replver Tool

The Replver tool is a reporting tool that provides a way to verify whether replication of both the public folder hierarchy and content occurred reliably across sites and throughout the organization. This tool runs against a master server, which verifies that a folder's contents on replicated servers are in sync with all replicated servers. The master server is the server that compares the public folder hierarchy and content of the other specified servers. The Replver tool verifies folder content, message content, MAPI properties between the master server and all replicated servers. When the tool finds an error, a message is displayed in the log file for verification and action.


Installing Replver

To install the Replver tool

  • From the Exchange\<operating system\platform>\PFTools\Replver subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Replver.exe to your computer.


Before You Use Replver

Before you use Replver, you need to have the Microsoft Exchange Client installed on the computer where you are planning to run this tool. In addition, the client version of Replver must be compatible with the Microsoft Exchange Server version. You can verify compatibility by creating a profile and connecting to the server(s) with the Microsoft Exchange Client. If the client can successfully connect and open both the private and the public stores, then the two versions are compatible and you are ready to run Replver.

Also, the Windows NT account logged on during execution of Replver needs to have Administration privileges on the Microsoft Exchange Server computer as "service account admin" on all sites the tool will access. To complete its work, the Replver program attempts to log on to the system attendant's mailbox on each server. If you don't have adequate permissions on the system attendant's mailbox, this logon will fail.


Using Replver

When Replver starts, it searches for a file called Replver.ini in your local directory.

To run the Replver tool

From the Config-Topology menu, choose Add Server.

Provide the appropriate information for your Microsoft Exchange organization, including the site and server name for each server you want to verify.

Start the comparison process by choosing the Start on the Run menu, or by choosing the Preferences-Options menu and changing the default settings of the tool.

Batch-Mode Operation

Replver can also run in a batch mode. For Help on running Replver in batch mode, type the following at the command prompt:

replver /?

The following options are displayed.

Option | Description
/b | batch mode
inifile | input filename (default = replver.ini)
output | output filename (default = replver.out)

Following is the typical command-line syntax usage for running Replver:

ReplVer [/b] [/I inifile] [/o output]

Note File names specified through the command line cannot contain spaces.

Verification Options

There are two parts to the Verification Options window. The first is output, and the second is the criteria used during the verification process. The Output Window Options section controls the amount of information placed into the log file for the tool.

The output options are shown below.

Option | Description
Show Time | Logs the date and time on the output.
Output to file | Writes all logging information to the file specified. Both universal naming convention (UNC) style and drive designator formats are supported when specifying the name and location where the log file will be created.
Overwrite Previous File | Overwrites an existing log file if selected.
Starting Folder | Controls the specific folder where the tool begins its verification.
Compare site folders alone | Compares only the special site folders (Schedule+ free/busy and the offline Address Book). This option verifies that there are no duplicate site folders from any site and that the local site folder's entry identification was obtained. It also correctly matches the local site's folder.
Folder tree root | Compares only folders starting from the root folder of the home server. The default is All Public Folders.
Other | Compares only the specific folder entered for the master server. If the Compare subfolders too option is also selected, then Replvr drills down the folder hierarchy.
Browse | Retrieves the complete public folder hierarchy and takes time to complete.

Comparison Options

Comparison options control what is compared between the home folders and replicated folder. The options are described in the following table.

Option | Description
Compare subfolders too | Starts from the specified starting folder and recursively compares the subfolders found within each subsequent hierarchical level. If it is not checked, only the starting folder is compared.
Compare messages | Compares all messages found in the folders. That is, verifies that the messages found in the home server are also on the replicated servers. However, the contents of the messages themselves are not compared.
Compare MAPI Properties | Ccompares all the supported MAPI properties within the folders and for the messages as well. If this option is not selected, then property-level verification will not be completed, and only folder mismatches will be reported.
Continue after Mismatches | Continues comparing other folders even if it finds mismatches on some folders. If this option is not selected, Replver stops after the first mismatch.

Replver Output Tags Configuration

Enabling different tags makes it possible for the advanced user to control the information to log, both to the Replver window and to the Replver logging file. However, you cannot control them independently.

The tag numbers 00 through 08 are used to specify the relevance of a log entry. The following table lists the tags and their descriptions.

Tag | Description
00: Start of new folder | Displays the next folder that is being compared in the Replver window and in the logging file.
01: Start of new message | Displays information about the messages that are being compared in the folder. Note that this information is only displayed once for all messages in a given folder.
Tag 02: Folder Mismatch | Displays information about folder mismatches.
03: Message Mismatch | Displays information about message mismatches.
04: Folder property dump | Displays a dump of all folder properties into the log file. Note This setting configures Replver to create an extensive dump of all folder properties and will cause the master server and other servers to become bogged down by the imposed demands of this comparison. This information is provided in very raw form and is usually only valuable for development purposes.
05: Message property dump | Displays a dump of all message properties. Note This setting configures Replver to create an extensive dump of all message properties and will cause the master server and other servers to become bogged down by the imposed demands of this comparison. This information is provided in very raw form and is usually only valuable for development purposes.
06: Folder property mismatches | Displays file information about folder properties that are mismatched.
07: Message property mismatches | Displays information about the message properties that are mismatched.
08: Summary | Selected by default. Displays a brief summary of all the errors and warnings that Replver found. It is highly recommended that this option remains enabled.

Sample log file output

The following sample output file was generated by running the Replver tool against a sample Microsoft Exchange platform. The Replver log file displays all the warnings and errors encountered while the tool was running. It also displays the specified information that is enabled in the output tags, as described in the previous section. All information displayed in the Replver log file is also displayed in the Replver output screen.

Aug 19 15:41:06: Attempting to logon to all the servers
Aug 19 15:41:11: Successfully logged on to all the servers. Now beginning tests!
Aug 19 15:41:11:
Aug 19 15:41:12: Tag 0: +++++Starting to compare folder maf_many_items +++++
Aug 19 15:41:12: Tag 6: Folder maf_many_items :
Aug 19 15:41:12: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:12: Tag 6: SERVER4 : 5
Aug 19 15:41:12: Tag 6: SERVER3 : 0
Aug 19 15:41:12: Tag 6: SERVER2 : 0
Aug 19 15:41:12: Tag 6: SERVER1 : 0
Aug 19 15:41:12:
Aug 19 15:41:12: Tag 1: Starting to compare messages in folder maf_many_items
Aug 19 15:41:12: Tag 3: Message with subject "Test posting for folder" not found on server SERVER3
Aug 19 15:41:12: Tag 3: Message with subject "Test posting for folder" not found on server SERVER2
Aug 19 15:41:12: Tag 3: Message with subject "Test posting for folder" not found on server SERVER1
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER3
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER2
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER1
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER3
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER2
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER1
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER3
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER2
Aug 19 15:41:12: Tag 3: Message with subject "" not found on server SERVER1
Aug 19 15:41:12: Tag 3: Message with subject "One of many postings..." not found on server SERVER3
Aug 19 15:41:12: Tag 3: Message with subject "One of many postings..." not found on server SERVER2
Aug 19 15:41:12: Tag 3: Message with subject "One of many postings..." not found on server SERVER1
Aug 19 15:41:12: Tag 1: Ended comparing messages in folder maf_many_items
Aug 19 15:41:12: Tag 0: +++++Finished comparing folder maf_many_items +++++
Aug 19 15:41:12:
Aug 19 15:41:13: Tag 0: +++++Starting to compare folder maf_many_items\alpha +++++
Aug 19 15:41:13: Tag 1: Starting to compare messages in folder maf_many_items\alpha
Aug 19 15:41:13: Tag 1: Ended comparing messages in folder maf_many_items\alpha
Aug 19 15:41:13: Tag 0: +++++Finished comparing folder maf_many_items\alpha +++++
Aug 19 15:41:13:
Aug 19 15:41:13: Tag 0: +++++Starting to compare folder maf_many_items\beta +++++
Aug 19 15:41:14: Tag 6: Folder maf_many_items\beta :
Aug 19 15:41:14: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:14: Tag 6: SERVER4 : 1
Aug 19 15:41:14: Tag 6: SERVER2 : 0
Aug 19 15:41:14:
Aug 19 15:41:14: Tag 1: Starting to compare messages in folder maf_many_items\beta
Aug 19 15:41:14: Tag 3: Message with subject "" not found on server SERVER2
Aug 19 15:41:14: Tag 1: Ended comparing messages in folder maf_many_items\beta
Aug 19 15:41:14: Tag 0: +++++Finished comparing folder maf_many_items\beta +++++
Aug 19 15:41:14:
Aug 19 15:41:15: Tag 0: +++++Starting to compare folder maf_many_items\delta +++++
Aug 19 15:41:15: Tag 6: Folder maf_many_items\delta :
Aug 19 15:41:15: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:15: Tag 6: SERVER4 : 1
Aug 19 15:41:15: Tag 6: SERVER2 : 0
Aug 19 15:41:15:
Aug 19 15:41:15: Tag 1: Starting to compare messages in folder maf_many_items\delta
Aug 19 15:41:15: Tag 3: Message with subject "Test posting for folder" not found on server SERVER2
Aug 19 15:41:15: Tag 1: Ended comparing messages in folder maf_many_items\delta
Aug 19 15:41:15: Tag 0: +++++Finished comparing folder maf_many_items\delta +++++
Aug 19 15:41:15:
Aug 19 15:41:15: Tag 0: +++++Starting to compare folder maf_many_items\Do you see me yet? +++++
Aug 19 15:41:16: Tag 6: Folder maf_many_items\Do you see me yet? :
Aug 19 15:41:16: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:16: Tag 6: SERVER4 : 5
Aug 19 15:41:16: Tag 6: SERVER1 : 0
Aug 19 15:41:16:
Aug 19 15:41:16: Tag 1: Starting to compare messages in folder maf_many_items\Do you see me yet?
Aug 19 15:41:16: Tag 3: Message with subject "One of many postings to Do you see me yet?..." not found on server SERVER1
Aug 19 15:41:16: Tag 3: Message with subject "One of many postings to Do you see me yet?..." not found on server SERVER1
Aug 19 15:41:16: Tag 3: Message with subject "One of many postings to Do you see me yet?..." not found on server SERVER1
Aug 19 15:41:16: Tag 3: Message with subject "One of many postings to Do you see me yet?..." not found on server SERVER1
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to Do you see me yet?..." not found on server SERVER1
Aug 19 15:41:17: Tag 1: Ended comparing messages in folder maf_many_items\Do you see me yet?
Aug 19 15:41:17: Tag 0: +++++Finished comparing folder maf_many_items\Do you see me yet? +++++
Aug 19 15:41:17:
Aug 19 15:41:17: Tag 0: +++++Starting to compare folder maf_many_items\Do you see me yet?\How about me? +++++
Aug 19 15:41:17: Tag 6: Folder maf_many_items\Do you see me yet?\How about me? :
Aug 19 15:41:17: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:17: Tag 6: SERVER4 : 4
Aug 19 15:41:17: Tag 6: SERVER3 : 0
Aug 19 15:41:17: Tag 6: SERVER2 : 0
Aug 19 15:41:17: Tag 6: SERVER1 : 0
Aug 19 15:41:17:
Aug 19 15:41:17: Tag 1: Starting to compare messages in folder maf_many_items\Do you see me yet?\How about me?
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER3
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER2
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER1
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER3
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER2
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER1
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER3
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER2
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER1
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER3
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER2
Aug 19 15:41:17: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER1
Aug 19 15:41:17: Tag 1: Ended comparing messages in folder maf_many_items\Do you see me yet?\How about me?
Aug 19 15:41:17: Tag 0: +++++Finished comparing folder maf_many_items\Do you see me yet?\How about me? +++++
Aug 19 15:41:17:
Aug 19 15:41:17: Tag 0: +++++Starting to compare folder maf_many_items\Do you see me yet?\How about me?\And me? +++++
Aug 19 15:41:18: Tag 6: Folder maf_many_items\Do you see me yet?\How about me?\And me? :
Aug 19 15:41:18: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:18: Tag 6: SERVER4 : 1
Aug 19 15:41:18: Tag 6: SERVER3 : 0
Aug 19 15:41:18: Tag 6: SERVER2 : 0
Aug 19 15:41:18: Tag 6: SERVER1 : 0
Aug 19 15:41:18:
Aug 19 15:41:18: Tag 1: Starting to compare messages in folder maf_many_items\Do you see me yet?\How about me?\And me?
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER3
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER2
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to How About Me?..." not found on server SERVER1
Aug 19 15:41:18: Tag 1: Ended comparing messages in folder maf_many_items\Do you see me yet?\How about me?\And me?
Aug 19 15:41:18: Tag 0: +++++Finished comparing folder maf_many_items\Do you see me yet?\How about me?\And me? +++++
Aug 19 15:41:18:
Aug 19 15:41:18: Tag 0: +++++Starting to compare folder maf_many_items\Do you see me yet?\How about me?\And me?\Me too? +++++
Aug 19 15:41:18: Tag 6: Folder maf_many_items\Do you see me yet?\How about me?\And me?\Me too? :
Aug 19 15:41:18: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:18: Tag 6: SERVER4 : 3
Aug 19 15:41:18: Tag 6: SERVER3 : 0
Aug 19 15:41:18: Tag 6: SERVER2 : 0
Aug 19 15:41:18: Tag 6: SERVER1 : 0
Aug 19 15:41:18:
Aug 19 15:41:18: Tag 1: Starting to compare messages in folder maf_many_items\Do you see me yet?\How about me?\And me?\Me too?
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER3
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER2
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER1
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER3
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER2
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER1
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER3
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER2
Aug 19 15:41:18: Tag 3: Message with subject "One of many postings to Me Too?..." not found on server SERVER1
Aug 19 15:41:18: Tag 1: Ended comparing messages in folder maf_many_items\Do you see me yet?\How about me?\And me?\Me too?
Aug 19 15:41:18: Tag 0: +++++Finished comparing folder maf_many_items\Do you see me yet?\How about me?\And me?\Me too? +++++
Aug 19 15:41:18:
Aug 19 15:41:19: Tag 0: +++++Starting to compare folder maf_many_items\epsilon +++++
Aug 19 15:41:19: Tag 6: Folder maf_many_items\epsilon :
Aug 19 15:41:19: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:19: Tag 6: SERVER4 : 1
Aug 19 15:41:19: Tag 6: SERVER2 : 0
Aug 19 15:41:19:
Aug 19 15:41:19: Tag 1: Starting to compare messages in folder maf_many_items\epsilon
Aug 19 15:41:19: Tag 3: Message with subject "One of many postings..." not found on server SERVER2
Aug 19 15:41:19: Tag 1: Ended comparing messages in folder maf_many_items\epsilon
Aug 19 15:41:19: Tag 0: +++++Finished comparing folder maf_many_items\epsilon +++++
Aug 19 15:41:19:
Aug 19 15:41:19: Tag 0: +++++Starting to compare folder maf_many_items\Gamma +++++
Aug 19 15:41:20: Tag 6: Folder maf_many_items\Gamma :
Aug 19 15:41:20: Tag 6: MisMatch in property PR_CONTENT_COUNT
Aug 19 15:41:20: Tag 6: SERVER4 : 2
Aug 19 15:41:20: Tag 6: SERVER2 : 0
Aug 19 15:41:20:
Aug 19 15:41:20: Tag 1: Starting to compare messages in folder maf_many_items\Gamma
Aug 19 15:41:20: Tag 3: Message with subject "One of many postings..." not found on server SERVER2
Aug 19 15:41:20: Tag 3: Message with subject "" not found on server SERVER2
Aug 19 15:41:20: Tag 1: Ended comparing messages in folder maf_many_items\Gamma
Aug 19 15:41:20: Tag 0: +++++Finished comparing folder maf_many_items\Gamma +++++
Aug 19 15:41:20:
Aug 19 15:41:20: Tag 0: +++++Starting to compare folder maf_many_items\New folder 1 +++++
Aug 19 15:41:21: Tag 1: Starting to compare messages in folder maf_many_items\New folder 1
Aug 19 15:41:22: Tag 1: Ended comparing messages in folder maf_many_items\New folder 1
Aug 19 15:41:22: Tag 0: +++++Finished comparing folder maf_many_items\New folder 1 +++++
Aug 19 15:41:22:
Aug 19 15:41:22: Tag 0: +++++Starting to compare folder maf_many_items\New folder 2 +++++
Aug 19 15:41:22: Tag 1: Starting to compare messages in folder maf_many_items\New folder 2
Aug 19 15:41:23:
Aug 19 15:41:23: Tag 8: ******************* Begin Summary*********************
Aug 19 15:41:23: Tag 8: WARNINGS were encountered during the comparisions
Aug 19 15:41:23: Tag 8: The following folders had the WARNINGS:
Aug 19 15:41:23:
Aug 19 15:41:23: Tag 8:     maf_many_items
Aug 19 15:41:23: Tag 8:     maf_many_items\beta
Aug 19 15:41:23: Tag 8:     maf_many_items\delta
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?\And me?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?\And me?\Me too?
Aug 19 15:41:23: Tag 8:     maf_many_items\epsilon
Aug 19 15:41:23: Tag 8:     maf_many_items\Gamma
Aug 19 15:41:23:
Aug 19 15:41:23: Tag 8: One or more major discrepancies were found
Aug 19 15:41:23: Tag 8: The following folders had the discrepancies:
Aug 19 15:41:23:
Aug 19 15:41:23: Tag 8:     maf_many_items
Aug 19 15:41:23: Tag 8:     maf_many_items\beta
Aug 19 15:41:23: Tag 8:     maf_many_items\delta
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?\And me?
Aug 19 15:41:23: Tag 8:     maf_many_items\Do you see me yet?\How about me?\And me?\Me too?
Aug 19 15:41:23: Tag 8:     maf_many_items\epsilon
Aug 19 15:41:23: Tag 8:     maf_many_items\Gamma
Aug 19 15:41:23:
Aug 19 15:41:23: Tag 8: Total number of folders compared : 12
Aug 19 15:41:23: Tag 8: Number of folders with warnings : 9
Aug 19 15:41:23: Tag 8: Number of folders with errors : 9
Aug 19 15:41:23: Tag 8: ******************* End Summary*********************
Aug 19 15:41:24: Tests done!

Replver.ini File

The Replver.ini file lists supported flags. The following table includes these flags and their descriptions.

Section

Flag and Setting

Description

[Debug]

Superuser=0 or 1

Default is 0.

If set to 1, Replver attempts to log on as the store owner, which enables you to work around access control list (ACL) restrictions. From that point on, the profile Replver creates also has super user privileges.

ListOnly=0 or 1

Default is 0.

If set to 1, Replver attempts to log on to the master server only and lists the entire public folder hierarchy into a file called Folders.out. This flag is useful for periodically verifying how the folders are growing. If this option is selected, then the Compare site folders alone option is automatically disabled.

TouchAll=0 or 1

It is highly recommended that you do not set this to 1. If you do, Replver affects every specified folder. In other words, Replver makes a change on every folder that will be replicated, and as a result, you will flood the system with replication mail.

NeverCreateProfile=0 or 1

Default is 0.

If set to 1, Replver will use existing profiles rather than trying to create new ones (or it will fail if the profile does not already exist).

[Replicas]

This section controls the replica list changes on public folders. The changes are managed from the master server in the list.

ReplicaAdd=0 or 1, ReplicaRemove=0 or 1, ReplicaSet=0 or 1

Only one (or none) of these should be set to 1. The following line controls which servers get added/deleted/set: ReplicaList=DN1,DN2,DN3.

This line represents a comma-separated list of server DNs. Server DNs are of the form:

/o=Organization/ou=Site/cn=Configuration/
cn=Servers

/cn=ServerName/cn=Microsoft Public MDB

If ReplicaAdd is set, these servers are added to the existing replica list of the folders.

If ReplicaRemove is set, these servers are removed from the existing replica list of folders.

If ReplicaSet is set, these servers are set to be the replica list of the folders (thus replacing the existing replica list).

These replica operations are started from the "Starting folder" specified in the Options property page and applied recursively, even if you have cleared the Compare Subfolders option.


RPC Counter Tool

The RPC counter is a performance tool that checks the number of remote procedure calls (RPCs) from an application to a Microsoft Exchange Server computer. The RPC counter can be used with clients running Windows 3.1, Windows for Workgroups, Windows NT Workstation, and Windows 95.

It's always important to design your application for maximum performance. Minimizing the number of RPCs for your application is the most important factor in improving performance. The RPC counter can alert you to inefficient code processes so that you can optimize these areas. Using the RPC counter to minimize the number of RPCs can improve your application's performance and decrease the load on the Microsoft Exchange Server computer.

The RPC counter is useful for determining the number of RPCs that are generated by:

  • MAPI calls
  • User actions
  • An application

All these examples for using the RPC counter are useful in determining the effect of system performance on the Microsoft Exchange Server from various sources.


Installing RPC Counter

Before you can use the RPC counter, you need to connect with the Emsmdb(32).dll file, which contains the necessary entry points for generating the RPC data. For details on RPC counter entry points, see "Understanding RPC Counter Entry Points." The Emsmdb(32).dll file is part of the Microsoft Exchange Client and Microsoft Exchange Server installation and is located in the Windows\System(32) directory.

You can access RPC counter data through several sample applications, depending on your computer's operating system.

To install the RPC counter sample applications

  • From the Exchange\<operating system\platform>\Developr\RPCCount directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the appropriate files (listed below) to your current working directory or somewhere in the system path.

    For Windows NT Workstation and Windows 95, copy Rpccnt.exe.

    For Windows 3.1 and Windows for Workgroups, copy Rpccnt16.exe.


Using RPC Counter

On the Windows 3.1 and Windows for Workgroups platforms, the RPC counter does not require any special setup.

To use RPC Counter on Windows NT Workstation and Windows 95 platforms

Set the following registry value to DWORD=1:

HKEY_LOCAL_MACHINE\Software\Microsoft\Exchange\Exchange Provider\RpcCounter

Restart all MAPI applications for the change to take effect.

Running Rpccnt.exe automatically sets the registry value to enable the RPC count.

Understanding the Fields of the RPC Counter

The RPC counter consists of the following nine fields, which indicate the number of RPCs generated for particular processes occurring on a Microsoft Exchange Server.

Field | Description
Total RPCs (IS+DS) | The number of RPCs going from all Microsoft Exchange clients on a given computer to all Microsoft Exchange Server computers they are connected to. This number includes RPCs to both the information store and the directory.
DS RPCs | The number of RPCs going to the directory. They are generated by MAPI calls related to address name resolution. All RPCs in this category need to be monitored carefully when optimizing MAPI clients. Note that DS RPCs are not counted on Windows 3.1 and Windows for Workgroups platforms.
IS RPCs | The total number of RPCs going to the information store. This number is the result of either MAPI calls accessing the message data or is generated automatically by the store provider code.
IS Bytes Out | The total number of bytes sent. It does not include the overhead of the RPC protocol. For example, the number reported by the network tools will be approximately 300 bytes higher per RPC.
IS Bytes In | The total number of bytes received. It does not include the overhead of the RPC protocol. For example, the number reported by the network tools will be approximately 300 bytes higher per RPC.
Progress RPCs (IS) | Indicates the RPCs generated automatically by the information store provider to monitor the progress of long operations.
Resent RPCs (IS) | Indicates the RPCs generated automatically by the information store provider if the RPC buffer is too small and the data needs to be resent.
Poll RPCs (IS) | Indicates the RPCs generated automatically by the information store provider to check for pending notification or to get the data after receiving a push notification. Indicates the RPCs generated directly by a MAPI call. This is the most important number to monitor when optimizing MAPI clients.

In addition, the RPC Counter dialog box displays an Auto Reset check box and a Reset Now button. The Auto Reset check box causes the counter data to be reset after four seconds of idle time. The Reset Now button resets the counter immediately.

Understanding RPC Counter Entry Points

When using the Rpccnt(16).exe sample application, the file calls the appropriate Emsmdb(32).dll entry points to obtain the counter data. The information in this section is provided if you need to call the entry points directly (for example, to integrate the RPC counter with other performance tools). The macro in Rpccnt.xls is an example of how to access the counter data from Visual Basic code.

The Emsmdb(32).dll file contains three entry points necessary for accessing RPC data. These entry points are the same for Windows 3.1, Windows for Workgroups, Windows NT Workstation, and Windows 95 platforms.

The three entry points are:

  • ScStatOpen, which initializes the count.
  • ScStatCollect, which collects the data.
  • ScStatClose, which closes the counter.

Examples

The following examples show the entry point declarations in both C and Visual Basic syntax:

C Syntax
SCODE FAR PASCAL ScStatOpen(void);
SCODE FAR PASCAL ScStatClose(void);
SCODE FAR PASCAL ScStatCollect(struct RPCStat *rgStat, ULONG *pcbStat);
Visual Basic Syntax
Declare Function ScStatOpen Lib "EMSMDB.DLL" () As Long
Declare Function ScStatClose Lib "EMSMDB.DLL" () As Long
Declare Function ScStatCollect Lib "EMSMDB.DLL" (ByRef rgStat As RPCStat, ByRef cbStat As Long) As Long

Because the data counting begins when ScStatOpen is called, a call to ScStatClose followed by ScStatOpen resets the counter. Because Windows NT Workstation and Windows 95 platforms have a per-instance data segment, you might have several counters counting independently. Windows 3.1 and Windows for Workgroups, however, have a shared data segment; therefore, resetting the counter is global to all instances.

Understanding the RPCStat Structure

The RPCStat structure contains the RPC counter values. These values are generated in the fields described previously in "Understanding the Fields of the RPC Counter." The RPCStat structure used by the entry points are:

C Syntax
struct RPCStat
{
 ULONG  cRPC;
 ULONG  cProgressRPC;
 ULONG  cResentRPC;
 ULONG  cPollRPC;
 ULONG  cbRPCOut;
 ULONG  cbRPCIn;
 ULONG  cDSARPC;
};
Visual Basic Syntax
Type RPCStat
 cRPC As Long
 cProgressRPC As Long
 cResentRPC As Long
 cPollRPC As Long
 cbRPCOut As Long
 cbRPCIn As Long
 cDSARPC As Long
End Type

The ScStatCollect entry point has a pointer as an argument to the RPCStat structure (allocated by the caller) and a pointer to a long variable containing the size of the RPCStat structure in bytes. On return, if there is no error (return value = 0), the RPCStat structure is updated with the counter values and the size variable is updated with the returned data size. If an error occurs (for example, "Out of memory"), the returned value is non-zero.


Self-Certification Form

The North American version of the Microsoft Exchange Client contains strong encryption software and is subject, therefore, to export restrictions under the International Traffic in Arms Regulations (ITAR) of the United States State Department. The State Department recently published an amendment to these regulations authorizing the temporary export of cryptographic products for use by U.S. citizens and lawful permanent residents when traveling abroad. This topic summarizes the conditions for taking advantage of the Personal Use Exemption and provides a sample form that qualified customers can use to comply with the State Department's record-keeping and self-certification requirements.

Please note that this document is provided for the convenience of Microsoft customers only. No warranty is made as to its accuracy, completeness, timeliness or suitability for any particular purpose. If you are uncertain whether you qualify for the Personal Use Exemption, or if you have any questions about its application to your particular circumstances, please contact the Department of State, Office of Defense Trade Controls, (703) 875-6643 or FAX (703) 875-6647, or consult with legal counsel.

The State Department may amend its regulations from time to time. For updates on amendments to the ITAR and on crypto policy generally, please see these links:

http://www.cdt.org/crypto/

http://www.epci.org/crypto/export_controls

http://www.enter.net/~chronos/cryptolog1.htm#laws


The Personal Use Exemption

On February 16, 1996, the U.S. government published an exemption for temporary export of cryptographic products for personal use. For the text of the regulations, see http://www.cdt.org/crypto/pers_exempt.html.

This exemption allows only U.S. citizens and lawful permanent residents to temporarily take abroad cryptographic products (such as encryption software installed on a laptop) for their personal use, without having to obtain an export license. The exemption imposes certain responsibilities on the traveler, including the following:

  • You may carry only a single copy of each encryption software product and only one encryption hardware device, and use the software product (s) only on a simultaneously temporarily exported hardware product.
  • The encryption products are for your personal use and not for copying, demonstration, marketing, sale, re-export, or transfer of ownership or control, and you must keep the encryption products in your possession or the possession of another U.S. citizen or lawful permanent resident traveling with you. A product is considered to be in your possession if you take normal precautions to ensure the security of the product by locking it in a hotel room, safe, or other comparably secure location. In addition, while in transit, you keep the product in your carry-on luggage, or locked in baggage accompanying you that has been checked with the carrier. When you leave or return to the U.S., the encryption product(s) must be with your accompanying baggage or effects. They may not be exported or imported in unaccompanied baggage, mailed or transmitted by any other means (for example, electronically); and the encryption product(s) must be returned to the U.S. at the completion of your stay abroad.
  • You may not carry the encryption products to destinations to which export is prohibited by a United Nations Security Council Resolution, or to which an export or export license would be prohibited by a U.S. statute, or to countries that have been determined to have repeatedly provided support for acts of international terrorism. The U.S. State Department informs us that at present prohibited destinations are Cuba, Iran, Iraq, Libya, North Korea, Sudan, Syria, and the People's Republic of China. Actually prohibited destinations may change at any time, and you should verify the current prohibited destinations before you make use of the exemption.
  • Upon request of a U.S. Customs officer, you must agree to submit the cryptographic products for inspection.
  • You must maintain for five years a record of each temporary export using the Self-Certification Form for Temporary Export of Encryption Software or its equivalent.
  • In any instance where a product exported is stolen, lost, copied, sold, or otherwise compromised or transferred while abroad, you must report this incident within 10 days of your return to the U.S., to the Department of State, Office of Defense Trade Control, Washington, D.C. 20520-0602.


Self-Certification Form for Temporary Export of Encryption Software

[ ] I certify that:

  • I am a U.S. citizen or lawful permanent resident (green card holder);
  • I complied with the conditions for use of the personal use exemption for temporary export of encryption products as published at 22 Code of Federal Regulations 123.27 and summarized above; and
  • I have no reason to believe that any of the temporarily exported cryptographic products listed below were stolen, lost, copied, sold, or otherwise compromised or transferred while abroad. Products containing encryption software: Microsoft Internet Explorer 3.0 128-bit version I entered and departed the following countries on the following dates (include the United States): Country (List All) Date Entered Date Departed

Products containing encryption software:

Microsoft Exchange, North American version

_____________________________________________

_____________________________________________

I entered and departed the following countries on the following dates (include the U.S.):

Country (List All)

Date Entered

Date Departed

______________________________________________|_______________|____

______________________________________________|_______________|____

______________________________________________|_______________|____

______________________________________________|_______________|____

Signature: ____________________________________

Name: ____________________________________

Date: __________________


Sentinel Tool

Sentinel monitors the status of Windows NT services, event logs, performance counters, and other types of data for many servers at one time. Sentinel also generates archives of the gathered data, and makes it available to other applications.

The Sentinel tool uses server groups and modules. A server group contains a list of Windows NT or Microsoft Windows 95 computers, or servers, which are accessible to Sentinel through a network. A module gathers data, and each module type gathers a different type of data. Sentinel includes the following modules: Service, Performance, and Event Log. For more information on server groups and modules, see "Understanding Server Groups and Modules."

A module gathers data of a specified type (such as the status of Windows NT services) and is loaded into a group. The same module can be loaded into many different groups, and each group can load many different modules. This enables you to create a new module, then distribute it to other users. Other users can have different groups, but the module always gathers the data for which it was originally configured.


Installing Sentinel

To install the Sentinel tool

  • From the Exchange\<operating system\platform>\Admin\Sentinel subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Sentinel.exe to your computer.


Using Sentinel

Because all modules are loaded into a group containing the same list of servers, it is easy to monitor different kinds of data (for example, a set of laboratory servers).

To run Sentinel

Locate the directory where you copied Sentinel.exe.

Double-click Sentinel.exe to start the Sentinel program.

Sentinel Configuration

The following figure illustrates the type of information displayed in Sentinel:

As this figure shows, there are two modules: Objects.pfm (a Performance module) and Generic.svc (a Service module) loaded into the My Lab server group, and one module loaded into My Office. In addition, the Parport service is running on all servers in My Lab, and there are 252 event objects being used on the server MT02. MT05 is not connected, probably due to permissions or network problems.

Understanding Server Groups and Modules

As mentioned earlier, a server group contains a list of servers that are accessible to Sentinel through a network. Each server name specified in Sentinel must match the network name configured in the Control Panel Network icon on that server.

Each of the three module types in Sentinel gathers a different type of data:

  • Service module — Obtains information on (and enables you to control) Windows NT services.
  • Performance module — Obtains the values of Windows NT performance counters.
  • Event Log module — Monitors Windows NT EventLogs for certain conditions, and enables quick viewing of remote event log entries. Unfortunately, the Event Log module is not yet completely implemented, so quick event log browsing only is available.

Configuring a Sentinel Service Module

To configure a Sentinel Service module

Start the Sentinel program.

In the Browser pane, right-click, and then choose Group, New.

Type a name (such as My Office) for the server groupyou are creating, and then choose OK.

Right-click the name of the group you just typed, and then choose New Server.

Type a server name, and then choose OK.

Right-click the group, and then choose New Module.

Select Service Module from the list, and then choose OK.

Your screen should appear as follows:

Adding Services to the Module

To select the services you want monitored by the Service module

From the Edit menu, choose Add Service. You can select a service that you want to browse, or you can type a service name.

Type a display name for the service. This name is displayed in the Sentinel grid.

Repeat the first two steps as necessary to list all services you want to monitor.

Service module example

The figure below illustrates how you can set options in the Service tab if:

  • The service you want monitored is the Microsoft Exchange Server message transfer agent (MSExchangeMTA).
  • You want to see the MSExchangeMTA service displayed as "MTA."

The following figure illustrates how the Sentinel Service module displays this information:

The following colored indicators notify you of your service's status:

Stopped

Started

Paused

Unknown (network problems, lack of permissions, or service doesn't exist)

To update status or to control the indicated services

  • Right-click on column headers such as MTA, row headers such as MT06, or individual cells.

To save the module for future use

  • From the File menu, choose Module, and then select Save As.

Data Output Mechanisms

Sentinel can distribute data it has collected from remote computers. This tool supports two types of remote data:

  • Database access objects (DAO)
  • Windows Sockets (WinSock) data
Database Access Objects

To enable database output, you must have DAO installed on the computer on which Sentinel is running. DAO is available in Microsoft Office and in other applications.

To create database output

From the Workspace menu, choose Data Output, and then select Database.

Select Output.

Browse to select a Microsoft Access database name, or type the name of the database.

The database can be manipulated from within Microsoft Access. Database format details will be published in the next update of the Sentinel tool.

WinSock Output

Sentinel supports WinSock output of all data collected through a WinSock server mechanism. Sample WinSock clients for Sentinel will be made available in the near future. Several sample clients were created to:

  • Translate all Sentinel-gathered data to World Wide Web pages.
  • Provide alerts based on numerous and complex conditions involving different types of data from Sentinel. An example of an alert would be the execution of a net send command if the Microsoft Exchange MTA queue is greater than 2000 and the MTA throughput is less than 200 bytes/sec, or if the MTA service status is anything other than running.

Tips for Using Sentinel

  • To monitor the operation of Sentinel on another computer, you must have administrative privileges on the Windows NT account where Sentinel is running.
  • You can temporarily disable server updates by right-clicking the server name in the module pane and then clearing the Enabled menu item. To turn this option back on, select Enable again.
  • The update interval default setting is every two minutes. You can set options for the update interval by using the Workspace Schedules menu.
  • To refresh all cells, right-click the upper-left cell (which is blank) and then select Update All, or press f5.


Server Space Client Extension Tool

The Server Space Client Extension tool enables you to display the total amount of space consumed on a Microsoft Exchange Server computer by your Microsoft Exchange Server mailbox folders. This tool is useful in situations where the amount of space allocated for each mailbox on the server is limited. The Server Space Client Extension Tool is also useful in situations where someone other than the owner manages a mailbox , because it displays the amount of space consumed by each server-based account in your viewer.


Installing the Server Space Client Extension Tool

There are two types of installation methods for the Server Space Client Extension tool:

  • Installation for Microsoft Windows clients
  • Installation for Windows NT clients

Installation for Windows Clients

To install the Server Space Client Extension tool on Microsoft Windows clients, follow the procedure below.

From the Exchange\<operating system\platform>\Client\SrvSpace directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Spcext32.dll to the Exchange directory on your computer.

Start Notepad and open the Windows\Exchng.ini file.

Add the following line under the [Extensions] section:

Server Space Extensions=4.0;c:\exchange\spcext16.dll;2;01010000000000

Save the file and close Notepad.

Restart the Microsoft Exchange Client.

Installation for Windows NT Clients

To install the Server Space Client Extension tool on Windows NT clients, follow the procedure below.

From the Exchange \<operating system\platform>\Client\Srvspace directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Spcext32.dll to the Exchange directory on your computer.

At the command prompt, switch to the Winnt35\System32 directory.

Type Regedt32, and then press Enter.

Switch to the HKEY_LOCAL_MACHINE window, and then locate this section: Software, Microsoft, Exchange, Client, Extensions.

Double-click Edit, and then choose Add Value.

For the Value Name, type Server Space, and then choose REG_SZ for Data Type.

Choose OK.

Paste the following into the String field: 4.0;c:\exchange\Spcext32.dll;1;01010000000000

Choose OK to add the entry, and then close the Registry Editor.

Restart the Microsoft Exchange Client.


Using the Server Space Client Extension Tool

After you install the Server Space Client Extension tool, Server Space appears as a new command on the Tools menu.

Note You can specify the amount of disk space that can be allocated to each user on a given server. Personal and public folders are displayed with "N/A" to indicate that items stored in these folders do not count towards a user's allocated disk space.

To display the total amount of space consumed by a user's mailbox folders on a Microsoft Exchange Server computer

  • From the Tools menu, choose Server Space.

To add the Server Space Client Extension button to your toolbar

From the Tools menu, choose Customize Toolbar.

Under Available Buttons, select the Server Space button, and then choose Add.

Position the button by using the Move Up and Move Down buttons.


Simple Mail Handler Tool

The Simple Mail Handler (SMH) tool is similar to the Microsoft Exchange Client Inbox Assistant, but doesn't require a connection to a Microsoft Exchange Server computer). The SMH tool also has more advanced filtering capabilities than those available in the Inbox Assistant.


Installing Simple Mail Handler

Use the following procedure to install the Simple Mail Handler tool.

To install Simple Mail Handler

For all operating systems except Windows NT Workstation, from the Exchange\<operating system\platform>\Client\SMH directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Mergeini.exe and the .dll for your operating system to the Windows\System directory on your computer.

For Windows NT Workstation, copy Mergeini.exe and the appropriate .dll to the System32 directory on your computer.

Run Mergeini.exe to add the Simple Mail Handler to the list of services available.

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then choose Add.

Select Sample Mail Handler, and then choose OK.


Using Simple Mail Handler

To start processing messages, you must set the properties for the Simple Mail Handler. You can set the SMH to perform the following:

  • Archive sent and deleted mail.
  • Add mail recipients to your personal address book (PAB).
  • Filter incoming mail based on custom filters.
  • Send out-of-office messages.
  • Move filters from one computer to another.

To archive sent or deleted mail

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the General tab.

To archive sent mail, under Sent Mail, select Archive sent mail into monthly subfolders. If you want monthly folders archived by year, also select Archive sent mail monthly folders by year.

To archive deleted mail, under Deleted Mail, select Archive deleted mail into monthly subfolders. If you want monthly folders archived by year, also select Archive deleted mail monthly folders by year.

A fully archived Sent Mail folder may have a hierarchy that looks similar to the following.

Sent Mail
|-- 1994
| |-- 10 October
| |-- 11 November
| |-- 12 December
|-- 1995
|-- 01 January

To add mail recipients to your personal address book (PAB)

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the General tab.

Under Sent Mail, select Add recipients to personal address book.

To enable filtering of incoming mail

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the General tab.

Under Incoming Mail, select Enable filtering of inbound messages.

Create at least one filter as described in the following procedure.

To create or edit a filter for inbound messages

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the Filters tab.

Choose New or select an existing filter, and then choose Properties.

In the Filter Name box, type a name for the filter.

In the Filter On box, select which message part to search for the value. Most of these parts correspond directly to the message boxes available in the Microsoft Exchange Client message dialog box.

In the Value contains box, type a value that you want the message to contain or not contain. If the message should not contain the value, select Filter messages that do not match this criteria.

In the Filter Target box, specify what to do with the messages that meet the criteria specified.

Caution The Filter Target option Delete messages from store removes the messages completely from the private information store; it does not move them to the Deleted Items folder. Setting a filter that, for example, specifies to delete messages if the Subject does not contain the value "Hello," deletes all messages that don't contain that value.

You can also set the Simple Mail Handler to send an automated response for messages meeting the filter criteria by using the Automated Response tab. You can set it to play a sound when mail arrives by using the New Mail Sounds tab.

To send an out-of-office message

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the Out-of-Office tab.

In the Out-of-office Message box, type your message. This box supports full rich text formatting.

Select Enable out of office handling.

To move filters to another computer

In Control Panel, double-click the Mail and Fax icon.

Select the Services tab, and then select Sample Mail Handler.

Choose Properties, and then select the Filters tab.

Choose Export, and then type a file name for the filter export file.

On the other computer, install the Simple Mail Handler, and select the Filters tab as described in steps 1 through 3.

Choose Import, and then select the filter export file created in step 4.

Unread Search Folders

Because the Simple Mail Handler can filter unread messages deep into a folder hierarchy, the Simple Mail Handler can also create a search folder in the root of the IPM_SUBTREE that searches the entire subtree for unread messages.

Known Issues

Below is a list of known issues with this release of the Simple Mail Handler.

  • The Simple Mail Handler archives are based on Greenwich Mean Time (GMT). This results in the archive folders being created several hours before the actual new month begins.
  • The Simple Mail Handler currently changes some of the formatting of the out-of-office text.


SwitchForms Tool for Microsoft Outlook

With the SwitchForms tool, you can easily switch between Microsoft Exchange Client and Microsoft Outlook. Although you can view the same e-mail folders in both applications, each application installs its own forms for composing and reading messages. If you need to run both Microsoft Exchange Client and Outlook on the same system, use SwitchForms to reinstall the correct forms.

The SwitchForms tool is intended for:

  • Helpdesk personnel who support and run both applications.
  • Microsoft Exchange Server public folder application designers who need to test their applications under both Microsoft Exchange Client and Outlook.
  • Systems professionals who run Microsoft Exchange Client for production use but need to evaluate Outlook.


Installing SwitchForms

Use the following procedure to install the SwitchForms tool.

To install Outlook SwitchForms

Insert the Tools and Utilities compact disc into the appropriate drive.

Copy the Outlook\Switchfm folder to a network or your hard disk and run SwitchForms from there.

Note SwitchForms requires the form configuration files from Microsoft Exchange Client, which are installed automatically by the Microsoft Exchange Client Setup program. SwitchForms also requires the Outlook 97 form configuration files, which are not installed when you choose a Typical installation during Office Setup. To install these files, rerun Office Setup and click Add/Remove. Select the Outlook option, and then select the Visuals for Forms Design option.


Using Switchforms

Before you use Outlook SwitchForms, quit Microsoft Exchange Client or Outlook.

To use Outlook SwitchForms

In the SwitchFm folder, double-click Regforms.exe.

In the Install forms for box, select either Microsoft Exchange Client or Microsoft Outlook to indicate which application you are switching to.

In the Search for form configuration files box, type the path for the form configuration files.

You do not need to specify a full path. SwitchForms searches the folder you specify and all of its subfolders. By default, Microsoft Exchange Client form configuration files are installed in C:\Windows\Forms\Configs. Outlook form configuration files are installed in C:\Program files\Microsoft Office\Office\Forms.

You can also automate the use of SwitchForms.

To use SwitchForms automatically

  • On the Start menu, click Run and type regform.exe\exchange or regform.exe\outlook, depending on which application you are switching from.

    Note If you have Microsoft Outlook or Microsoft Exchange Client files running on your computer, you may receive errors when you run SwitchForms. To correct this problem, reboot your computer and run SwitchForms again. When SwitchForms has successfully completed, you will receive a message. If you do not receive the message, reboot your computer and run SwitchForms again.


UNIX Mail Source Extractor Tool

The UNIX Mail Source Extractor tool automates the transfer of user accounts, messages, and associated information from a UNIX e-mail system to Microsoft Exchange Server. This tool is intended for use by system administrators.

The Source Extractor tool extracts the data to migration files, which can then be imported to Microsoft Exchange Server. To import data to Microsoft Exchange Server, you can use the Microsoft Exchange Migration Wizard Import from Migration Files option.

Because many organizations with UNIX RFC822-based messaging systems require the rich content capabilities provided by Microsoft Exchange Server, the extractor provides a way to extract messages from the mail spooler, as well as messages filed in private folders.

The following table defines terms you should be familiar with:

Term | Description
Pine | Text-based UNIX e-mail client written and owned by the University of Washington.
DAPI | Microsoft Exchange Directory Import/Export.
Elm | Text-based UNIX e-mail client which is distributed in most standard UNIX distributions.
RFC822 | The standard for the format of Advance Research Projects Agency (ARPA) Internet text messages.


Installing the UNIX Mail Source Extractor

To install the UNIX Mail Source Extractor tool

From the Exchange\Samples\UnixSE subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy the UNIX source code to your computer.

Because the UNIX Mail Source Extractor is provided as source code, a C compiler on the host computer, or a compiler capable of compiling to the host computer is required to produce the migrate file. For more information, see the compiler documentation for your version of UNIX.


Using the UNIX Mail Source Extractor

Before attempting to use this utility, you should be familiar with the RFC822 standard. The Unix Source Extractor parameter file is referenced throughout this document. For more information on this file, see the "User Interface" section.

Note that the migrated files will be named mmddhhmm.pkl, mmddhhmm.pri, <loginID>.pri, and <loginID>.sec. The mmddhhmm.pri file will only contain the Directory section. If a file exists with the same time, the minutes value (mm) will be incremented by one minute.

Command-Line Syntax

To perform the migration

  • Use the following syntax to begin the migration process:

    migrate [-u<User File>] [-r] [-a] [-m] [-d<path>] [-p</path/Parameter File>] [-? | -h | -H]

The following table lists the command-line options available in the UNIX Mail Source Extractor tool, and their functions:

Command

Class

Function

-u<file name>

Optional

Indicates a file containing a list of the users to be migrated. (Note that a file name must be present.) The file can be in password file format (/etc/passwd) or a list of logon IDs with one logon ID per line. This file will be used to obtain the necessary information (such as the user ID, info section, and home directory) if the line contains 6 colons, otherwise the password file will be used. This overrides the lowest UserID variable in the Parameter file.

Example:

File 1:
Smith:x:173:175:M Smith:/user/fac/smithj:/bin/csh
billlee:x:175:110:Z Billlee:/user/grad/Billlee:/bin/csh
Steelej:x:176:110:S Steelej:/user/grad/steelej:/usr/local/bin/tcsh
File 2:
annd
johnd

-r

Optional

Create custom recipients in Microsoft Exchange. (Does not create accounts or mail.)

-a

Optional

Create accounts in Microsoft Exchange. (Does not migrate mail.)

-m

Optional

Migrate mail to Microsoft Exchange (assumes custom recipients or mailboxes exist.)

-d<path>

Optional

Overrides the default location where the extracted data will be located. The default location is the current directory.

-p

Optional

Fully qualified path to the parameter file including the file name. Use the parameter file to indicate additional parameters. The parameter file can be located anywhere with any name. (Default is current directory.)

-?, -h, -H

Optional

Displays command-line Help.

The -r, -a, and -m commands migrate only the specific type of information indicated. However, if they are used together, they will migrate all of the types. Following are examples of common command-line procedures:

To migrate custom recipients and mail

  • Type migrate -r -m

To migrate accounts and mail

  • Type migrate -a -m

To migrate custom recipients and accounts

  • Type migrate -r -a

    Note This command line will generate an error message on Import.

Before You Perform the Migration

During the extraction, the process must have read access to all files and directories where the mail exists. Read access on all files to be migrated is the minimum requirement for extraction. Root or Superuser access can be used. All mail queues must be empty. No modifications are made to the passwd file.

A system of UNIX computers in a cluster will require special consideration for migration. When you perform the migration, you must have access privileges to log on to the computer that contains the mail spooler. (IMAP access is not sufficient.) If it is not possible to log on to and access both directory locations of the user's home directories and the mail spooler, migration must be run twice; once against the home directories and once against the mail spooler.

Content Migrated

Account information and messages are migrated to Microsoft Exchange. The account information is accessed through the /etc/passwd file along with the "hostname" command, which uses the /etc/hosts file. Mail data is migrated from the mail spool (/var/spool/mail or /usr/spool/mail) and from files located in the home directories of the individual users.

Account Information

Account information is taken from the /etc/passwd file. The passwd file has the field format of "login-name:password:user-ID:group-ID:info:directory:program". The properties of the new accounts are shown in the following table.

New Microsoft Exchange Property | Old UNIX Property
Common-name | Login-name field of the passwd file.
Display-name | The first entry of the info field of the passwd file by default. For more information, see the discussion of the info field following this table.
Office | The second entry of the info field of the passwd file by default. For more information, see the discussion of the info field following this table.
Phone | For more information, see the discussion of the info field following this table.
Secondary-proxy-addresses | "migrate:smtp:<login-name>@< hostname>". Login-name is from the passwd file. Hostname is to be located by the UNIX c call gethostname,which uses the /etc/hosts file.
Home-server | Home-server will be "~server" which, when imported into Microsoft Exchange, sets the home server to the current directory server.

The mapping of the info field can be adjusted to individual systems. In most systems, the info field takes the form of "display name,office,phone," although the UNIX system does not recognize phone but places both office and phone information in the office output form. You can specify directory import/export fields in the parameter file, for mapping data stored in the field. This enables the following information mappings:

/etc/passwd | Directory Import/Export
Bill Lee | Display-name
Lee, Bill | Surname,Given-name
Bill Lee,10B,x55555 | Display-name,Office,Phone

If the info field does not contain the correct number of comma delimiters corresponding to the directory import/export template, the UNIX Mail Source Extractor does not create an error. If the info field does not have enough comma delimiters, the extractor accepts the data that is present and treats the other fields as having no data. If the info field contains too many comma delimiters, the extractor will treat the data between them as part of the last directory import/export field.

By default, only users with a user-ID over 99 are migrated. It is possible to override this default by changing the LOWEST_USER_ID_TO_MIGRATE value in the param.h file or by passing a specific user list file to the source extractor on the command line. Custom recipient creation is supported.

To start migration with directory synchronization

If you want to start migration with directory synchronization, follow the procedures below to create Microsoft Exchange custom recipients for UNIX IDs.

Use the UNIX source extractor to extract the custom recipients.

Import the resulting migration files by using the Migration Wizard.

To create Microsoft Exchange custom recipients on the UNIX side

To create Microsoft Exchange custom recipients on the UNIX side, follow the steps outlined below.

Use Directory Export to create a list of Microsoft Exchange users.

Create UNIX accounts for all of the users.

Create the .forward file in order to forward mail to Microsoft Exchange.

Message Data

The message data to be migrated comes from the system mail spooler and the user's personal storage. The mail spooler location is configurable in the parameter file and the default is set in a header file of the C code, param.h. Note that Param.h is the template for the parameter file that can be called on the command line. This value will only have to be set once per computer if it is set in the header file prior to being compiled.

The default location is /var/spool/mail/. Inbox, Send Items, Outbox, and Deleted Items folders are created for each user with messages from the UNIX spooler being moved to the Microsoft Exchange Inbox folder.

The source extractor will also read mail from personal storage. Mail in personal storage has to be in the same format as mail in the spooler. Messages cannot have been touched by certain Emacs e-mail clients or any other client that modifies the standard message format.

For personal storage, both ~/Mail/ and ~/mail/ will be checked by default. The parameter file can be used to change those defaults. When addresses are extracted from message headers, the UNIX comma delimiter will be changed to semicolons. The names of the UNIX files in each folder will become the names of the Microsoft Exchange folders and the original capitalization is retained. The UNIX "sent" and "sent-mail" folders will be moved to the Microsoft Exchange Sent Items folder. Subfolders, however, will not be migrated.

The folder locations will map as shown below:

New Microsoft Exchange Location | Old UNIX Location
Inbox | /var/spool/mail/ (System spooler)
Sent Items | Sent or Sent-Mail folders
UNIX Folder Name (Root Level) | UNIX-Folder-Name

The message properties will map as shown below:

New Microsoft Exchange Property | Old UNIX Property
Sender | The second From line in the header. If only one exists, the first From line will be used. The second From line usually contains a more descriptive address. These names will most likely have the form "AnnDevon@xyz (Part-time Developer)," depending upon the form in the actual mail.
To | To line in the header.
Cc | Cc line in the header.
Bcc | Bcc line in the header.
Subject | Subject line in the header.
Send-date | Send Date in the header's second From line. If it does not exist, then Received Date is used. If neither exists, the default is to Import time.
Received-date | Received Date in the header's first From line. If it does not exist, then Send Date is used. If neither exists, the default is to Import time.
Priority | 1 (normal).
Unread | Mail will be marked as unread unless the header field Status exists and has "r" as the value.
Unsent | Always FALSE.

Note Pine has a concept of unsent mail that is specific to Pine and dependent on the file name of the local mail store. The UNIX source extractor ignores this value and places mail in the "postponed-msgs" folder, which requires no special handling.

No calendar or address book information will be migrated.

User Interface

The user interface for the Source Extractor is command-line only. After the process has started, there is no interaction between the program and the user. All control data is passed to the source extractor through the command line and parameter file at run time.

The UNIX shortcut for directory specification of "~billlee" for specifying "/home/billlee" is not allowed.

Parameter File

A sample parameter file (param.txt) is provided and the defaults are listed in the following table for each variable. If the syntax of the file is incorrect, migration will stop with an error message. All fields, with the exception of "Local Mail Store Location," can have only one value. An exclamation mark (!) as the first character of a line denotes that the line is a comment only.

Variable Name | Default | Description
DAPI string | Display-name,Office | The Directory Import string that describes the content of the info field in the password file. This information is not verified by the UNIX Mail Source Extractor. (< 200 characters.)
Lowest User ID to Migrate | 100 | The User ID of the first user to be migrated. This is set at 100, because it is recommended not to give users a number under 100. This default does not migrate system accounts such as root, diag, sysadm, bin or news. If an illegal User ID exists for the user, the account will be migrated without an error. (Integer between -1 and 10000, retrieved with scanf.)
Mail Spool Location | /var/spool/mail/ | Location of the mail spooler. The default is pulled from the param.h file, which can be changed at compile time. (< 200 characters)
Local Mail Store Location | /mail/ /Mail/ | The directory where personal mail is stored. The value "/mail/" is translated to "~home/mail/". Ten locations are supported (most sites have a maximum of three). This field is multivalued, if this variable is listed more than once in the parameter file, the last occurrence will not overwrite the previous values. Each value must be entered one per line. (< 200 characters.)

Sample Param.txt File

!Directory Import string that describes the content of the Info
!field in the password file.
DAPI string: Display-name,Office

!UserID of the first user to be migrated. This is set at 100
!because it is recommended not to give users a number under 100.
!This default does not migrate accounts such as: root, diag,
!sysadm, bin, and news.
Lowest UserID to Migrate: 100

!Location of the Mail spooler.
Mail Spool Location: /var/spool/mail/

!Directory where personal mail is stored
Local Mail Store Location: /mail/
Local Mail Store Location: /Mail/


MS Mail Tools

Microsoft Exchange and Microsoft Mail provide a variety of tools that can be used to troubleshoot problems and automate tasks in your organization.

Note These tools are in the Exchange directory on the BackOffice Resource Kit II Utilities compact disc.

The tools listed below are described in the "Microsoft Mail for Windows Tools" section of this chapter:

Microsoft Mail Tools

  • Acctonme Tool
  • Dumpfld Tool
  • Dumpidx Tool
  • Dumpkey Tool
  • Escntlr Tool
  • Fixfld Tool
  • Fixidx Tool
  • Gimport Tool
  • Listuser Tool
  • Movefold Tool
  • Mvcal Tool
  • Netdump Tool
  • Revert Tool


Microsoft Mail for Windows Tools

The Microsoft Mail for Windows tools are a collection of utilities designed to repair and maintain the database for Microsoft Mail for PC Networks. These tools are recommended for administrators only. The procedures described in this section apply to versions 2.1 and later of Microsoft Mail, except where noted. Note that the Microsoft Mail for Windows tools support I386 platforms only.


Installing the Microsoft Mail for Windows Tools

To install the Microsoft Mail for Windows tools

  • From the Exchange\Common\MSMail subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy all files to your computer.


Using the Microsoft Mail for Windows Tools

The following table lists the Microsoft Mail for Windows tools included on the BackOffice Resource Kit, Part Two compact disc. More complete descriptions of each utility follow this table.

Warning To prevent the loss of important data, always back up the Microsoft Mail for Windows database before you use any of the utilities described in this document.

Tool | Description
Acctonme.exe | Creates an Admin.nme file from the following existing Microsoft Access files: Access.glb, Access2.glb, and Access3.glb.
Dumpfld.exe | Displays the contents of a folder (.fld) file.
Dumpidx.exe | Displays the contents of a folder index file (.idx files, including Foldroot.idx).
Dumpkey.exe | Lists owners of calendar files.
Escntlr.exe | Removes, installs, and displays the status of enhanced security on a version 3.0 or 3.2 postoffice.
Fixfld.exe | Recovers corrupted folder files.
Fixidx.exe | Recreates a folder index file.
Gimport.exe | Creates a group from a file.
Listuser.exe | Displays the mailbox names and associated eight-digit ID numbers.
Movefold.exe | Enables you to transfer folders to another postoffice.
Mvcal.exe | Renames a corrupted calendar file located on the server.
Netdump.exe | Displays the external postoffice and gateway routing files.
Revert.exe | Resets the unread count for a Microsoft Mail message file (.mmf).


Acctonme Tool

The Acctonme tool completely rebuilds the postoffice address list. It can be used with Microsoft Mail version 2.1 and later postoffices.

Acctonme does not directly access the global address list (GAL) in Microsoft Mail versions 3.0 and 3.2. Because the GAL contains the names from the local postoffice, it requires rebuilding after this process is complete. For more information on rebuilding the GAL, see your Microsoft Mail documentation

When to Use Acctonme

Use Acctonme only when both the Admin.nme and Adminshd.nme files are deleted or irrevocably damaged. If only one of the files is damaged or missing, you can replace the damaged file with a copy of the undamaged file.

Side Effects of Using Acctonme

Running this tool will result in the loss of all external postoffice names, gateway names, and local group names in the postoffice address list. Given the structure of the address list file and its connection to the group subsystem of the database, you must delete all postoffice groups before proceeding.

Note As with all Microsoft Mail utilities, it is highly recommended that you back up your Microsoft Mail database before running Acctonme. You must also back up the Admin.nme file in the NME subdirectory by typing the following at the command prompt in the Microsoft Mail Database subdirectory:

copy \nme\admin.nme \nme\admin.old

As a precaution, print a report of all postoffice groups by starting the Microsoft Mail Administrator program (Admin.exe) and selecting Local-Admin, Group, Print, <File or Printer>. If necessary, you can use this list later to recreate the groups.

To rebuild your postoffice list by using Acctonme

Delete all postoffice groups by starting the Microsoft Mail Administrator program (if you haven't already), and then select the Local-Admin, Group.

Delete each group in the postoffice.

If the group has an associated group folder, you will be prompted to delete the folder.

Switch to the drive and path where the Microsoft Mail database is located and then set the Admin.exe file in the NME subdirectory to zero bytes by typing the following command at the command prompt:

nul > \nme\Admin.nme

When you type this command, you may receive a "File not found" error message. Disregard this message.

From the root directory where the Microsoft Mail database is stored, run the ACCTONME tool. It will rebuild the postoffice address list so that it contains only local mailbox names (no messages are generated upon completion).

Copy the Admin.nme file to Adminshd.nme by typing the following command from the root directory where the Microsoft Mail database is stored:

Copy \nme\admin.nme \nme\adminshd.nme

To recreate the postoffice groups, select Local-Admin, Group, Create in the Microsoft Mail Administrator program. Use the list generated as a guide to recreating the postoffice groups.

To recreate the lost external user names, choose the Address menu option in the Mail Administrator program or use the Import tool.

If you are using Microsoft Mail 3.0 or 3.2, start Rebuild.exe to recreate the global address list.

Restoring Postoffice Address Lists

Any changes in the postoffice address list since the last backup, such as new users, will be lost when you restore the list. Therefore you need to restore the Admin.nme, Adminshd.nme, Access.glb, Access2.glb, and Access3.glb files from the backup files.

Adding a Lost Name into the Address List

If you are rebuilding the Admin.nme file because a record is missing (for example, you see a particular user name from the Microsoft Mail Administrator program, but you do not see the user when you try to compose a message), use the following procedure.

To add a name back into the address list

If there is not a 00000000.nme file in the Nme subdirectory of the Microsoft Mail database, create a new user and substitute that user's eight-digit ID number for 00000000 in the following procedure. The user's eight-digit ID number can be found by running the Listuser.exe program located on the database utilities disk.

In the NME subdirectory of the Microsoft Mail database, copy 0000000.NME to 00000000.old. (If the file is 0 bytes long, do not perform this step.)

In the same directory, copy Admin.nme to 00000000.nme, and then make the current directory the root of the Microsoft Mail database.

Start the Microsoft Mail Administrator program and then select Local-Admin, Modify. Select the user name to be added to the address list and then record the mailbox name and alias. Return to the top level of the Microsoft Mail Administrator program, select Config, Password, and record the network and postoffice names.

Quit the Microsoft Mail Administrator program and start the MS-DOS client.

Log on as the administrative user.

Add the missing user to the personal address list by choosing Address, Enter (select Microsoft Mail Address Type if you have any gateways installed), and then selecting the mailbox, postoffice, network, and alias names.

Quit the Microsoft Mail program and then switch to the NME subdirectory of the Microsoft Mail database. Copy 00000000.nme to Admin.nme and Dminshd.nme.

In the same directory, copy 00000000.old to 00000000.nme or create a 0-byte 00000000.nme file by typing the following at the command prompt:

Type aaa > 00000000.nme

When you type this command, you will receive a "File not found" error message. Disregard this message.

Removing a Record

If you are rebuilding the Admin.nme file because you are trying to remove a record (for example, if you see a particular user when you try to compose a message, but you do not see the user from the Mail Administrator program), use the following procedure:

To remove a record

If there is not a 00000000.nme file in the NME subdirectory of the Microsoft Mail database, create a new user and substitute that user's eight-digit ID number for 00000000 in the following procedure. Then use Listuser.exe (located in the database utilities disk) to determine the ID number for that user.

In the NME subdirectory of the Microsoft Mail database, copy 0000000.nme to 00000000.old. However, do not perform this step if the file is zero bytes long.

In the same directory, copy Admin.nme to 00000000.nme, then make the current directory the root of the Microsoft Mail database.

Start the Microsoft Mail program and log on as the administrative user.

To remove the record, from the Address menu, choose Delete (or Remove if you are running Microsoft Mail). Select the user and then press ENTER.

Quit Microsoft Mail.

Switch to the drive where the Microsoft Mail database is located. In the NME subdirectory, copy 00000000.nme to Admin.nme and Adminshd.nme.

Restore 00000000.nme from 00000000.old, or if the file was zero bytes long, you can zero out the file by typing the following at the command prompt:

aaa > 00000000.nme


Dumpfld Tool

The Dumpfld tool generates a diagnostic file for the contents of a folder file. Dumpfld works with Microsoft Mail version 2.1 and later postoffices. However, it does not provide information from Microsoft Mail 3.0 or 3.2 mail message files (.mmfs).

When to Use Dumpfld

Use this tool to verify the contents and/or the integrity of a folder file.

Side Effects of Using Dumpfld

There are no side effects from using this tool because it performs a read-only function on the folder file.

To run Dumpfld

  • At the command prompt, type Dumpfld and an option. The following syntax must be used:

    dumpfld [-ml] <folder_file name>

The following table lists the command-line options available in Dumpfld and their descriptions:

Option | Description
-m | Displays all items in the folder file, including deleted items.
l | Prints extended record information.
<folder_file name> | The folder file in the current directory where the information is to be dumped.

Example for Using Dumpfld

To dump all information about all items in the older file 00000002.fld to the computer screen, type the following at the command prompt:

dumpfld -ml 00000002.fld

Typically, .fld files are stored in the Folders subdirectory. Private folders are stored in the Loc\000xxxxx directory, where 000xxxxx is the ID number for that user. Public, group, and shared folders are stored in the Pub subdirectory. Folder files can also be stored locally on a user's hard disk drive or on an alternate network location.

To direct the output to a file, use the MS-DOS redirection symbol ">" and a file name. Following is a sample command that will direct the output of Dumpfld to the Results.txt file:

dumpfld -ml 00000002.fld > results.txt

When you use the -m command-line switch, you may receive the following error message: "Error: Failure to read record." Disregard this error message.


Dumpidx Tool

The Dumpidx tool generates a diagnostic dump of a folder index file. Dumpidx works with Microsoft Mail 2.1 and later postoffices. However, it does not dump information from Microsoft Mail 3.0 or 3.2 Mail message files (.mmfs).

When to Use Dumpidx

Use this tool to verify the contents and/or the integrity of a folder index file.

Side Effects of Using Dumpidx

There are no side effects from using this tool because it performs a read-only function on the folder index file.

To run Dumpidx

  • Type the following at the command prompt (with an option):

    dumpidx -[ecpns] <index_file name>

The following table lists the command-line options available in Dumpidx, and their descriptions:

Option | Description
-e | Displays the same information as the -c option, with additional information about the associated folder file. This includes the name of the folder, access rights, and the number of items in the folder.
-c | Displays the header information for the selected file. This includes the location in the file, attributes, and file name, comment and owner fields for each record in the index file.
-p | Displays the folder names for each of the records in the index file.
-n | Displays the folder file names associated with each record in the index file.
-s | Displays the same information as the -c option, with size information for each folder file.
<index_file name> | The index file in the current directory for which information is to be dumped.

Example for Using Dumpidx

To dump folder size information for all items in the index file 00000002.idx to the computer screen, type the following at the command prompt:

dumpidx -s 00000002.idx

Typically, .idx files are stored in the Folders subdirectory. Private folder indexes are stored in the Loc\000xxxxx directory, where 000xxxxx is the ID number for that user. Public, group, and shared folders are stored in the Pub subdirectory. Index files can also be stored locally on a user's hard disk drive or on an alternate network location.

To direct the output to a file, use the MS-DOS redirection symbol ">" and a file name. The following command will direct the output of Dumpidx to the file Results.txt:

dumpidx -s 00000002.idx >results.txt


Dumpkey Tool

A user's online calendar file is not named with the same eight-digit ID number as the user's mail message file, nor is it named with the user's name (for security reasons). You can use the Dumpkey tool to find out which online calendar files belong to which users.

To run Dumpkey

  • Copy the Dumpkey.exe file to the Cal subdirectory of the postoffice by typing the following at the command prompt (this example assumes that the Microsoft Mail database is located on drive M):

    copy dumpkey.exe m:\cal\dumpkey.exe

To use this tool correctly, follow the command-line syntax format shown below:

dumpkey schedule.key

When to Use Dumpkey

You can use this program if you want to find the owner of a particular calendar (.cal) file on the server.

Side Effects of Using Dumpkey

There are no side effects to using the Dumpkey tool because it is a read-only file.


Escntlr Tool

The Escntlr tool enables you to turn off enhanced security and turn it on for the postoffice. This tool can only be used with Microsoft Mail 3.0 and 3.2 postoffices. Enhanced security is a double-encrypted password that stops Microsoft Mail 2.x clients from accessing the postoffice. It is unrelated to Advanced Security, which is a method of creating a connection to the postoffice that a user cannot access.

When to Use Escntlr

Use this program to display or change the status of enhanced security.

Side Effects of Using Escntlr

Enhanced security will be added or removed, and the files containing the user accounts will be modified.

To run Escntlr

  • Use the following command-line syntax format:

    escntlr <admin> -p<password> [-s] [-r or -i] [-d<drive>] [-?]

The following table lists the command-line options available in Escntlr and their descriptions:

Option | Description
<admin> | The name of the administrator for this postoffice (required).
-p<password> | Specifies the password for the administrator.
<admin> | Specifies the name of the administrator for this postoffice (required).
-s | Displays the status of enhanced security only. This overrides all other options, except for the drive option (-d).
-r | Removes enhanced security if installed.
-i | Installs enhanced security if not installed.
-d<drive> | Specifies the drive where the Microsoft Mail database is located (the default is drive M).
-? | Displays the Help screen.

Note As with all Microsoft Mail utilities, it is highly recommended that you back up your Microsoft Mail database before running Escntlr. At a minimum, you should back up the Glb subdirectory by typing the following command from the root of the Microsoft Mail database directory:

xcopy \glb \bak\ /s /v

This command copies the entire GLB subdirectory to a new directory called Back.

Removing Enhanced Security

The setup program for Microsoft Mail 3.2 removes or adds enhanced security to the postoffice.

To remove enhanced security

  • Type the following at the command prompt:

    escntlr admin -p<password> -r

Installing Enhanced Security

To install enhanced security on drive N

  • Type the following at the command prompt:

    escntlr admin -p<password> -i -dn

Viewing Enhanced Security Status

To view the status of enhanced security on drive N

  • Type the following at the command prompt:

    escntlr -dn -s


Fixfld Tool

The Fixfld tool attempts to rebuild folder files from their current contents. Fixfld can be used only with Microsoft Mail 2.1 and later postoffices. It does not work for Microsoft Mail 3.0 or 3.2 mail message files .

When to Use Fixfld

Use this tool only when a public or private folder is corrupted.

Side Effects of Using Fixfld

There are no side effects when using Fixfld because this tool is only specified on the command line.

To run Fixfld

  • Use the following command-line syntax format:

    fixfld <saved_folder_file new_folder_file>

The following table lists the command-line options available for Fixfld, and their descriptions:

Option | Description
<saved_folder_file> | The file where the copy of the old folder file was saved
<new_folder_file> | The name of the newly created folder file.

Backing Up Your Microsoft Mail Database

As with all Microsoft Mail utilities, it is highly recommended that you back up your Microsoft Mail database before running Fixfld. Typically, .Fld files are stored in the Folders subdirectory. Private folders are stored in the Loc\000xxxxx directory, where 000xxxxx is the ID number for that user. Public, group, and shared folders are stored in the Pub subdirectory. Folder files can also be stored locally on a user's hard disk drive or on an alternate network location.

To back up your Microsoft Mail database

At the command prompt, create a backup copy of the folder file by typing:

copy <file name>.fld <file name>.old

Rename the folder file by typing: ren <filename>.fld <filename>.sav

Build a new copy of the folder file from the Folders\Pub subdirectory by typing:

fixfld <file name>.sav <file name>.fld

Start the Microsoft Mail Administrator program and then chooose Local-Admin, Folders, Compress. This is necessary to ensure that the changes are stored.

You only need to perform one folder-compress step for multiple folder rebuilds. If a folder is no longer referenced by its corresponding index file, it is safe to delete the folder file.

Rebuilding a User's Private Folder

The following steps assume that you are not running Microsoft Mail version 3.0 or 3.2 of the Microsoft Mail Windows client software, because this program handles folders differently than other clients.

If you are trying to rebuild a user's private folder, you can restore the corrupted folder from the backup copy in one of three ways:

  • Restore the entire private folder subdirectory, in which case all information placed in any folder since the last backup will be lost.
  • Restore the corrupted folder file and run the Fixidx tool to rebuild the index file. For more information on running this tool, see the "Fixidx Tool" section. If you follow this option, you will lose only the information placed in the corrupted folder since the last backup.
  • You can recover the folders from a backup copy by using the following procedure:

    Restore a backup of the entire Microsoft Mail database to a different location on the server or to a local hard disk.

    Run the Microsoft Mail program with the -d option to specify where the restored database is located. If Microsoft Mail is located on the local hard disk, use the Subst command. For example, type Subst p: C:\Maildb, then type Mail -dp.)

    Log on to Microsoft Mail as the user with the corrupted folder files.

    Archive all of the user's folders by selecting Options, Folders, Folders, Archive.

    On the production postoffice, reset the user's folders, de-archive the folders into the user's active mailbox by choosing Options, Folders, Folders, and De-Archive from the Microsoft Mail program, and then remove the restored copy of the Microsoft Mail database.

    If none of the user's private folders are accessible, you can reset that user's folder from the Microsoft Mail Administrator program. Select Local-Admin, Folders, Reset, select the user, and then press ENTER. This will move the folder location back to the postoffice and create a new .idx file with no folders existing.

Restoring a Shared Folder

If you are trying to rebuild a shared folder, you can restore the folder from the backup copy in one of the following ways:

  • Restore the entire shared folder subdirectory, in which case all information placed in any shared folder since the last backup will be lost.
  • Restore the corrupted folder file and then run Fixidx to rebuild the index file, in which case you will lose only the information placed in the corrupted folder since the last backup.


Fixidx Tool

The Fixidx tool rebuilds the folder index file from records of all of the folders in a subdirectory. You can use Fixidx with Microsoft Mail version 2.1 and later postoffices. However, it has no effect on Microsoft Mail version 3.0 or 3.2 message files.

When to Use Fixidx

Use this tool only when a folder index is deleted or irrevocably damaged.

Side Effects of Using Fixidx

Running this program will result in the loss of all folder names. Rebuilding Foldroot.idx when there are group folders on that postoffice will make the group folders inaccessible, because Fixidx resets the group folder type to that of a shared folder. To repair damaged files, use the following procedure:

To run Fixidx

  • Use the following command-line syntax:

    fixidx< fld_dir idx_file owner>

The following table lists the command-line options available in FIDIDX, and their descriptions:

Option | Description
<fld_dir> | Indicates the directory that contains the folder (.fld) files that should be used to build the new index file. For example, to rebuild the index (.idx) file for the public folders system when the Microsoft Mail database stored on drive M, use M:\Folders\Pub.
<idx_file> | Indicates that the file will be used to store the new index file. This can be any name but should be the name of the index file for the directory you are dealing with. For example, with the prior example (for <fld_dir>), use M:\Folders\Pub\Foldroot.idx.
<owner> | Displays the name of the person who will have ownership of all the folders in the index that is created. This parameter is necessary if you want to enable folders to be modified (using the Options, Folders, Modify command). Other users are given Read, Write, Delete privileges. For example, to give the administrator access to these folders, this field should be 00000000. If you are giving access to a different user, you must know that user's eight-digit Microsoft Mail ID number.

Note As with all Microsoft Mail tools, it is highly recommended that you back up your Microsoft Mail database before running Fixidx. You must also back up the folder subdirectory you will be working with.

Rebuilding the Index file for Public Folders

To rebuild the index file for public folders

  • Type the following at the command prompt:

    fixidx m:\folders\pub m:\folders\pub\foldroot.idx 00000000

    This assumes your Microsoft Mail database is on drive M.

Rebuilding the Index File for Private Folders

To rebuild the index file for a user's private folders

First you need to determine the eight-digit ID number for that user by using the Listuser tool included on the database utilities disk.

After you know the ID number, type the following command (assuming your Microsoft Mail database is on drive M). Substitute the user's eight-digit ID number for <hexid>:

fixidx m:\folders\loc\<hexid> m:\folders\loc\<hexid>.idx <hexid>

If the index file for a user's private folder is corrupted or missing, you can reset that user's folder from the Microsoft Mail Administrator program. Select Local-Admin, Folders, Reset, select the user, and then press enter.

Repairing Damaged Group Folders

Use the procedure outlined below to change the byte parameter, to indicate the current status of the folder as that of a shared folder. Note that you cannot directly change the folder status back to that of a group folder. Instead, the folder is designated as a shared folder.

Before you run DEBUG on the .Fld file, you must run Fixfld on that folder.

Run DEBUG on the folder in question and then change the 49th byte from 00 to 03 by typing the following at the command prompt:

debug 00000003.fld

Then type :

e0131

DEBUG displays the following: xxxx:0131 02, where xxxx will vary from computer to computer.

Type the following, pressing enter after each line:

03

w

q

This resets the folder's internal definition to be that of a shared folder. The administrator must then create a new group folder, move the messages from the old folder to the new folder, and then delete the old folder to restore group access.


Gimport Tool

The Gimport tool creates, deletes, and modifies postoffice address list (POL) groups that contain Microsoft Mail users and X.400, FAX, SMTP, SNADS, PROFS, and MHS gateway users.

You can create groups in the POL that contain users defined on the local postoffice, as well as users defined on external postoffices or as gateway addresses. However, any groups that contain external users cannot be exported to other Microsoft Mail postoffices, and these groups cannot be included in directory synchronization. This limitation can create challenges for organizations that have several Microsoft Mail postoffices and users that need to send mail to groups containing users on several different postoffices.

There is no method for creating such cross-postoffice groups only once and then exporting these groups to other postoffices. The groups can be exported through the Microsoft Mail Administrator program, and when a user on the postoffice where the group was created sends mail to the group, all users (local and external) receive the message. However, when a user on another postoffice sends mail to an exported group, only those users defined on the postoffice where the group was created receive the mail message; external users in that group do not.

The only way to enable all users on all postoffices to successfully send mail to the same group of users is to create that group on all postoffices. For large organizations with several postoffices and thousands of users, this process can be very time-consuming and prone to error.

Gimport.exe makes this process easier. Although you still need to create the groups on every postoffice, you can automate this task to a certain degree. To use Gimport, manually create the group on one postoffice, and then extract the group information to a text file. The information in the text file can then be imported to other postoffices.

System Requirements

  • An 80286 or higher computer.
  • A minimum of 500K of extended or expanded memory. The actual amount of extended or expanded memory required may be greater than 500K, depending on the number of entries in the POL (Adminshd.nme).
  • MS–DOS version 3.3 or later.

When to Use Gimport

Use this tool to create, delete, or modify groups on the postoffice. If the group is small (fewer than 20 users), and contains only local users, or if the number of groups is small (fewer than 5 groups), the Microsoft Mail Administrator program can be more efficient in creating and maintaining the group.

Side Effects of Using Gimport

New groups are deleted or created, and existing groups are modified.

Note Before you run Gimport, you must add users to a group so that they are present in the POL. You can automatically add users to the POL by running the Import. exe with the -a option. The Import.exe file ships with Microsoft Mail and is located in the Mailexe subdirectory. For more information on the Import tool, see your Microsoft Mail documentation.

To run Gimport

  • Use the following command-line syntax format and include the appropriate option(s):

    gimport admin [-d[drive|path]] [-ffilename] [-i[filename]] [-llogfile] -ppassword [-r] [-s] [-v] [-x[file name]] [-y] [-?]

The following table lists the options available in Gimport and their descriptions.

Option | Description
admin | The mailbox logon ID of a Microsoft Mail administrator (required).
-d[drive|path] | Specifies the location of the Microsoft Mail data files. Drive specifies the drive on which the Microsoft Mail data files reside (the default is drive M). Path specifies the path to the Microsoft Mail database files.
-ffilename | Specifies the output file that contains the group definition and the group users. This file is not compatible with the Import.exe tool.
-i[filename] | Specifies an output file that does not contain the group definition. This file is compatible with the Import.exe tool. The default name for this file is Grpusers.dat.
-llogfile | Specifies the location of the log file.
-ppassword | Specifies the mailbox password of the Microsoft Mail administrator (required).
-r | Removes all postoffice address list groups and resets all the group files to default values. The following files are reset: Admin.grp, Adminshd.grp, Group.glb, Grpmem.glb. In addition, the groups are removed from the Admin.nme and Adminshd.nme files. The records in the Access.glb file are modified to reset the point into the Grpmem.glb. All the Mem files are removed from the Mem directory.
-s | Prevents name sorting of the members of the groups extracted from the postoffice. By default, sorting is turned on. This option can be used to speed up execution of the program when you extract extremely large groups.
-v | Displays and logs detailed logging information.
-x[filename] | Specifies which groups are to be extracted. If no file name is specified, all groups are extracted.
-y | Overrides the confirmation message.
-? | Displays the Help window.

File Formats

The output file created with the -f option is a text file containing the group transactions.

  • The file consists of the group name, followed by the group members.
  • The format of the Import-compatible file created with the -i option is the same, except that the group name is not included.
  • The format of the file used by the extract option (-x) is only the alias of the group, with each alias on a separate line.

Group transaction file

Each group transaction is on a separate line. Each of these lines contains four mandatory entries.

The first entry's transaction type is either G, A, D, R, P, or #. The transcription type must appear in column 1. The following are transaction type codes and their description.

Transaction Type Code | Description
G | Adds/modifies the following group to the POL. The list of members should follow this line. If the group does not exist in the POL, it is assumed to be a new group and is created. If the group does exist, the transactions following this line are assumed to be modifications to the existing group.
A | Adds the following address to the last group defined by the last G transaction type.
D | Deletes the following address from the last group defined by the last G transaction.
R | Replace the following group with the users defined in following transactions. All transactions for this group can only be of type A.
P | Purges (deletes) the following group from the POL.
# | Comment line. Ignored.

The second entry is the alias. The alias can be from 1 to 30 characters long, and must start in column 3 or be separated from the first entry by a tab.

The third entry is the address type. Follow it with a colon (:). This address type must start in column 34 or be separated from the second entry by a tab. Only the following address types are supported: PCM, X400, FAX, SMTP, SNADS, and PROFS.

The fourth entry is the address. It immediately follows the address type and must be that type of address. For more information about the proper address format, see the Import Tool section in your Microsoft Mail documentation.

Sample input file

# New group to be created
G Group 1                PCM:network1/30po1/trial
A User 0                 PCM:network1/30po1/auto0
A User 1                 PCM:network1/30po1/auto1
# Group to be deleted
P Trial Group            PCM:network1/30po1/trial
# New group with gateway addresses
G Gateway Group 1          PCM:network1/30po1/gtwygrp
A Sample User 0            SMTP:user0@dummy.host.edu
A Sample User 1            SNADS:SNADSNET/DGN1/user1
A Sample User 2            PROFS:VMGATE/NODE1/user2

Files to Back Up

As with all Microsoft Mail utilities, it is highly recommended that you back up your Microsoft Mail database before you run Gimport.exe. As a minimum, you should back up the following directories:

  • Glb
  • Nme
  • Grp
  • Mem

Examples for Using Gimport

The following examples illustrate how Gimport can be used in your organization.

Example 1: Automatically copying a group from one postoffice to another.

This example assumes that you have created a group named "Test Group" on Postoffice 1 (on drive M) that contains only the user "Administrator" for Postoffice 1 and you want to create this group on Postoffice 2 (on drive N).

To copy a group from one postoffice to another

  • Type the following at the command prompt:

    gimport -dm admin -ppassword -xgrpext.inf -fgroups.ext -igrpusers.dat

    • Grpext.inf—a text file that contains the name of the group to be extracted. For this example, the Grpext.inf file contains the following text: Test Group.
    • Groups.ext—the file to which the group information is written. The Groups.ext file contains the following information:

      # - Microsoft Mail Group Import Program v3.0b

      # - Started: 05/13/94 07:49

      G Test Group PCM:NET/PO/TestGroup

      A Administrator PCM:NET/PO/Admin

    • Grpusers.date—the file to which only user information and not group information is written to. This file contains the following information:

      # - Microsoft(R) Mail Group Import Program v3.0b

      # - Started: 05/13/94 07:55

      # The data in this file is for use with the Microsoft Mail Import.exe tool

      A Administrator PCM:NET/PO/TestGroup

Importing the group into Postoffice 2

To import the names of users in the group to the POL on Postoffice 2

  • Note that all the users in the group must be present in the POL on Postoffice 2. At the command prompt, type:

    import -dn admin -ppassword -a -fgrpusers.dat

    After typing this command, you will receive warning messages for any users who already exist on Postoffice 2. These messages can be ignored.

Creating the group on Postoffice 2

To create the group on Postoffice 2 and add the users to it

  • Use the Groups.ext file (containing the G transaction type). At the command prompt, type the following:

    gimport -dn admin -ppassword -fgroups.ext

Example 2 - Resetting all group files on a postoffice

In certain cases, you may want to reset all the group files on a Microsoft Mail postoffice.

To reset all group files on a postoffice

  • Use the Gimport.exe file. At the command prompt, type the following:

    gimport -dm admin -ppassword -r

    (The above example assumes that the postoffice on which you wish to reset all the group files exists on drive M.)

Creating log files

You can create a log file when working with any of the above examples.

To create a log file

  • Use the -l<log file> command-line option. To enable verbose logging, use the
    -v command-line option.


Listuser Tool

The Listuser tool displays a list of all users on a given postoffice, including their associated eight-digit user ID numbers (these numbers are used by the Microsoft Mail system to identify each individual user). Listuser works with Microsoft Mail version 2.1 and later postoffices. This tool also displays the size of the .mmf files on the server, and can search for a specific name on the postoffice.

When to Use Listuser

Use this program whenever you need to know the ID number associated with any of your users.

Side Effects of Using Listuser

There are no side effects when using Listuser, because it is a read-only tool.

To run Listuser

  • Use the following command-line syntax format:

    listuser <admin> -p<password> [-d<drive>] [-f] [-x] [-n<name>] [-s] [-?]

The following table lists the command-line options available in Listuser, and their descriptions:

Option | Description
<drive> | The drive where the Microsoft Mail database is located (the default drive is M).
-f | Displays the user's full name in addition to the alias (optional).
-x | Displays the delete status of the users and any deleted users (optional).
-n<name> | Displays only those names that match the <name> parameter. This option by itself searches on the alias and the hexademical ID. If the option is specified, the full name field is searched.
-s | Displays the size of any .mmf files that are on the server.
-? | Displays the Help window.

To determine a user's ID number

You can also determine a user's ID number by performing the following steps:

Run Microsoft Mail and log on as the user.

From the Options menu, choose Folders, and then choose Private Storage.

Select Local-Storage.

Type c:\ (or whichever local drive is available).

Quit Microsoft Mail.

At the MS-DOS prompt, type Dir C:\*.idx. The file name displayed is the user's ID number.

To return the folders back to the server, restart Microsoft Mail.

From the Options menu, choose Folders, and then choose Private Storage.

Select Server.


Movefold Tool

The Movefold tool enables a user's private folders to be moved to another postoffice. This tool is required when a user is changing physical locations and becomes a member of a new Microsoft Mail postoffice. Note that Movefold will work only with Microsoft Mail 2.1x postoffices and Microsoft Mail 3.0 or 3.2 postoffices that do not have enhanced security enabled. Also, this tool only affects the MS-DOS client's private folders.

When to Use Movefold

You can use this program whenever you want to move a user's folders from one postoffice to another.

Side Effects of Using Movefold

There are no side effects when using Movefold, because this tool performs read-only operations on the Microsoft Mail database files.

To run Movefold

  • Use the following command-line syntax format:

    movefold <mailbox> -p<password> -d<drive> [-e<exportfile> | -i<importfile>]

The following table lists the command-line options available in Movefold, and their definitions:

Option | Description
<mailbox> | The user's current mailbox name.
<password> | The user's current password.
<drive> | The drive where the Microsoft Mail database is located.
<exportfile> | The export file name.
<importfile> | The import file name.

Files to Back Up

As with all Microsoft Mail utilities, it is highly recommended that you back up your Microsoft Mail database before running Movefold. You must also make a backup of the folder subdirectory you will be working with.

Also, make sure each Microsoft Mail user moves his or her private folders back to the server by running the MS–DOS Microsoft Mail client and selecting Options, Folders, Private-Storage, Server. Do not proceed until all private folders have been moved back to the file server postoffice.

Because the Movefold tool must use the user's password, you may have to start the Microsoft Mail Administrator program and use the Local-Admin, Recover commands to recover all of the passwords back to the global default password.

Note The Movefold tool must be run from a drive where there is enough disk space to store all of an individual's private folders. All the parameters of the Movefold tool must be used to guarantee its performance.

Examples of Moving Folders

To move the folders of a user named Chris

Type the following at the command prompt to export the folders from Chris's user account on the postoffice on drive M to the Chrfold.arc file:

movefold chris -ppassword -dm -echrfold.arc

Type the following at the command prompt to import the Chrfold.arc file into Chris's user account on drive N:

movefold chris -ppassword -dn -ichrfold.arc.

If the destination postoffice is not currently available, the Movefold import command can be run at a different time.

To enable a folder owner to move folders

Start the MS–DOS Microsoft Mail client and then log on to the user's current mailbox.

Choose Options, Folders, Folders, Archive.

Select each folder, and then choose the file name you want to save it as. Make a note of the folder name.

Start the MS–DOS Microsoft Mail client and log on to the user's new mailbox.

To recreate each folder, choose Options, Folders, Create.

Choose the folder name and the access permissions you want associated with that folder.

To restore folders to the archived folders, choose Options, Folders, Folders, De-Archive.

Select each folder and select the file name.


Mvcal Tool

A user's online calendar file is not named with the same eight-digit ID number as the user's Microsoft Mail message file, nor is it named with the user's name (for security reasons). You can use the Mvcal tool to locate a specific user's online calendar file (if, for example, the file is damaged).

When to Use Mvcal

Use this program if a .cal file is corrupted or damaged, and you want to find the owner of that calendar.

Side Effects of Using Mvcal

This tool will find the calendar file for the user name specified and rename it <username>.bad. After the calendar file is renamed, a new file will be created the next time the user logs on. This new calendar file will be created from the user's local calendar file.

To run Mvcal

  • Use the following command-line syntax format:

    mvcal <user name> [-d<drive> -p<password>]

The following table lists the command-line options available in Mvcal, and their descriptions:

Option | Description
<user name> | Displays the name of the user with the corrupted calendar file.
<drive> | Displays the path to the Microsoft Mail database (the default is drive M).
<password> | Shows the password for the Schedule+ administrator (not the Microsoft Mail administrator).

Example of Renaming a Calendar File

To rename John Doe's calendar file on drive N

  • Type the following at the command prompt:

    mvcal JohnDoe -dn -ppassword

    where the Schedule+ administrator's password is "password."


Netdump Tool

The Netdump tool displays information for all external postoffices and gateways defined on the given postoffice. The tool displays the network/postoffice names, the mailbag (.mgb) file for the external postoffice, whether the postoffice is routed indirectly via another postoffice, the definition (.xtn) file where the external postoffice is located, and the connection type (LAN, modem, or X.25) for the postoffice.

For gateways, the Netdump tool displays the following:

  • Gateway name
  • Gateway postoffice (if the given postoffice is a downstream postoffice)
  • Mailbag for the gateway
  • Definition file (.XTN)
  • File for the gateway
  • FFAPI, PROFS, and SNADS gateways
  • Node name and node mailbag

The current version of Netdump recognizes the PROFS, SNADS, MCI, X.400, MSMAIL (Mail Connection), FAX, SMTP, AT&T, MHS, and FFAPI gateways.

When to Use Netdump

Use this program to display the external postoffice and the gateway routing and definition information.

Side Effects of Using Netdump

There are no side effects to using this tool, because it is read-only.

To run Netdump

  • Use the following command-line syntax format:

    netdump <admin> [-d[<drive>|<path>]] [-f<file name>] [-l<log file>]
    -p<    password>[-v] [-?]

The following table lists the options available in Netdump and their descriptions:

Option | Description
<admin> | The mailbox logon ID of a Microsoft Mail administrator (required).
-d[<drive|path>] | Specifies the location of the Microsoft Mail data files. <Drive> specifies the drive on which the Microsoft Mail data files reside (the default is drive M). <Path> specifies the path to the Microsoft Mail database files.
-f<file name> | Specifies the file in which to save the network/postoffice information that is displayed.
-l<log file> | Specifies the file to which logging information is written (optional).
-p<password> | Specifies the mailbox password of the administrator ID used (required).
-v | Displays/logs detailed information.
-y | Suppresses video output.
-? | Displays the Help menu.

To display the information for a postoffice located on drive M

  • At the command prompt, type:

    netdump admin -ppassword -dm.


Revert Tool

Sometimes corruption in a Microsoft Mail message file (.mmf) can make the "read" and "new" counters indicate that a message has not been read, when in fact it has been read and there are no new or unread messages. The Revert tool resets these counters to correct the problem. After the counters are reset, the Microsoft Mail client recalculates and displays the correct values.

The CheckMMF tool included with version 3.0b or later of Microsoft Mail for Windows can also reset these counters, but this tool can actually cause the file to be corrupted if the .mmf file is not otherwise damaged.

When to Use Revert

Use this program when the "new" or "unread" counters displayed by the Microsoft Mail for Windows client in the message file are not correct. You can also use the Listuser tool to determine the hexadecimal ID of the user whose .mmf needs to be reset. For more information on Listuser, see the "Listuser Tool" section.

Side Effects of Using Revert

There are no side effects to using the Revert tool.

To run Revert

  • Type the following at the command prompt:

    revert <file name>

    where <file name> displays the path to the .mmf that is to be reset. The full path must be specified.


MS BackOffice Resource Kit: Part Two Release Notes (Readme.wri file)

Copyright © Microsoft Corp. 1996, 1997

This online document contains important information that is not included in the online Help or the printed documents that are part of the Microsoft BackOffice Resource Kit: Part Two. In particular, this online document contains information not available in other information sources about installing the Resource Kit tools. This document also contains information on changes to the tools that occurred after publication of the printed documents.

Additional tools for Microsoft Exchange Server are available at the following Web site: http://microsoft.com/technet/appfarm/. Patches with the most current corrections to the tools and their documentation are available on the Internet at the following Microsoft FTP site: ftp://ftp.microsoft.com/bussys/backoffice/reskit.


Using Write or WordPad to View This Document

You can view this document using either Write or WordPad.

If you enlarge the Write or WordPad window to its maximum size, this document will be easier to read. To do so, click the Maximize button in the upper-right corner of the window. Or open the Control menu in the upper-left corner of the Write window (press ALT+SPACEBAR), and then choose the Maximize command.

To move through the document, press PAGE UP or PAGE DOWN or click the arrows at the top and bottom of the scroll bar along the right side of the Write or WordPad window.

To print the document, choose the Print command from the File menu.

For Help on using Write or WordPad, press F1.

To read other online documents, choose the Open command from the File menu.


Contents

1.0 Setup for the Resource Kit Software

    1.1 Hardware-Platform and Other Issues
    1.2 Setting Up the Resource Kit Tools
    1.3 Additional Setup Information
    1.4 TechNet

2.0 User Notes

    2.1 Microsoft Systems Management Server Tool Notes
    2.2 Microsoft Exchange Server Tool Notes
    2.3 Microsoft SQL Server Tool Notes
    2.4 Microsoft SNA Server Tool Notes
    2.5 Help File Corrections

3.0 Other Online Documents

4.0 Resource Kit Support Policy

5.0 File List for the Microsoft BackOffice Resource Kit: Part Two CD-ROM

    5.1 Microsoft BackOffice Resource Kit File List
    5.2 Microsoft Systems Management Server File List
    5.3 Microsoft Exchange Server File List
    5.4 Microsoft SNA Server File List
    5.5 Microsoft SQL Server File List

6.0 Directory Structure of the Microsoft BackOffice Resource Kit: Part Two CD-ROM


1.0 Setup for the Resource Kit Software

In the root directory of the Microsoft BackOffice Resource Kit: Part Two CD-ROM, there is the overall README.WRI file that you are currently reading and a SETUP.EXE file for installing most of the Resource Kit software. Utilities that are not installed by the main Setup program have their own installation program in their own directory or subdirectory.

The following is a list of the main directories on the Microsoft BackOffice Resource Kit: Part Two CD-ROM. For a list of all the first- and second-level directories on the CD-ROM, see Section 6.0, "Directory Structure of the Microsoft BackOffice Resource Kit: Part Two CD-ROM."

\Alpha

\apps

\Exchange

\Help

\I386

\Libs

\Sms

\Sna

\Sql

\Win95

Important Log on as a member of the Administrators group before starting Setup because many of the tools require administrator privilages.

Finally, these tools have not been localized: they have been written and tested in English only. Using these tools with a different language version of Microsoft® Exchange Server, Microsoft Exchange Client, or Systems Management Server may produce unpredictable results.


1.1 Hardware-Platform and Other Issues

The following is a list of issues relating to various Resource Kit utilities that are included in this release of the BackOffice Resource Kit, Part Two. These are utilities that were not available at the time of release, or that do not work on one hardware platform or another. Hopefully, most of these issues will be resolved by the next release.

Attmwiz Tool - Not available.

Dupproxy.exe - Works only on Windows NT.

Exchbkup.exe - Not available.

PFReports (various .rpt files for Crystal Reports) - Not available.

Phone.exe - Works only on Windows NT.

Storstat.exe - Not available


1.2 Setting Up the Resource Kit Tools

The Setup program for the Microsoft BackOffice Resource Kit: Part Two requires Microsoft Windows NT® version 3.51 or later. In Windows NT 4.0 or later, the Setup program autoruns.

To set up the Resource Kit tools on Windows NT 3.51:

Start Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: setup, then choose OK.

The Microsoft BackOffice Resource Kit: Part Two Setup program displays a License Agreement dialog box. If you agree to accept the terms of the license agreement, Setup continues.

Follow the instructions on the screen to complete Setup.

There are two options for installing the Microsoft BackOffice Resource Kit: Part Two on your hard disk: Typical Setup and Complete\Custom Setup. Typical Setup installs all the Resource Kit files onto your hard disk and requires a maximum of 27 MB of free space. Use Complete\Custom Setup to choose specific components and minimize the amount of space used on your hard disk.

Setup creates program groups for the BackOffice Resource Kit with icons for some of the tools. For more information about these tools, choose the BackOffice Tools Help (Borktool.hlp) icon in the BackOffice ResKit program group.

Setup also adds the directory name you choose for installing the tools to the path System environment variable. (If you want to change your path double-click the System icon in Control Panel after the Resource Kit installation is complete.)

Setup installs the Microsoft Systems Management Server Client applications in a different directory.


1.3 Additional Setup Information

This section contains information on installing applications that are not installed by the main Resource Kit Setup program, or that require additional configuration. Instructions for installing many of the tools are in the Exchtool.hlp and Smstools.hlp Help files.

1.3.1 Additional Setup Information on Systems Management Server Tools

Some of the Systems Management Server tools access DLL files in a directory that is not in your path. These tools must be run from the directory in which the DLL files are located. In most cases, the DLL files are located in Sms\Site.srv\<platform>.bin, where <platform> is I386 or Alpha. The tools that require this are documented in Smstools.hlp.

For information on the NetBoot floppy, installing Performance Monitor counters, or installing Visual Test 4 and upgrading to Systems Management Server 1.2, see the Smstools.hlp Help file.

To set up Pollinv.exe:

Start Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu, or choose the Start button, and then choose Run.

Type cd_driveletter:\SMS\Ntinvcol\platform\instpoll.exe, and then choose OK.

Follow the instructions on the screen to complete Setup.

Manually start the service by typing the following at the command line prompt: net start sms_nt_inventory_file_collector

1.3.2 Additional Setup Information on Microsoft Exchange Server Tools

This section contains information on installing applications that are not set up by the main Resource Kit Setup program, or that can be installed using several installation procedures, or that require additional configuration. Instructions for installing many of the tools are in the Exchtool.hlp. Help file. Some instructions in the Help file apply only to Windows 95. Additional setup information for these tools is included here.

To install Crystal Reports for Exchange:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Admin\Crystal to set up this program.

To install the Schedule+ Address Book Assistant on Non-Windows 95 platforms:

Copy Schedaba.exe from cd_driveletter:\Exchange\<operating system\platform>\Client\Schedaba to your Windows directory.

Copy all of the dynamic-link libraries (DLLs) from cd_driveletter:\Exchange\<operating system\platform>\Client\Schedaba to your Windows\System directory.

Run Schedaba.reg to add an entry for the tool to the registry.

To install the EFD Hand Code Agent:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can be installed directly from the BackOffice Resource Kit Part Two Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Developr\EFDhandc to set up this program. See Exchtool.hlp for setup information.

To install the Mailbox Cleanup Agent:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can be installed directly from the BackOffice Resource Kit: Part Two Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Admin\MBClean to set up this program. See Exchtool.hlp for setup information.

To install the Microsoft Exchange Administrative Mailbox Agent:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can be installed directly from the BackOffice Resource Kit Part Two Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Admin\AdminAgt to set up this program. See Exchtool.hlp for setup information.

To install the Microsoft Exchange Server Modeling Tool:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can be installed directly from the BackOffice Resource Kit Part Two Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Modeling to set up this program:

In Program Manager, choose Run from the File menu.

In the Run dialog box, type cd_driveletter:\Exchange\<operating system\platform>Modeling\Setup, and then choose OK.

Follow the instructions on the screen to complete Setup.

The Microsoft Exchange Server Modeling Tool is an addition to the Windows NT Domain Planner. You need to install the Domain Planner before installing the Modeling Tool.

To install the Windows NT Domain Planner:

Start Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROMin the CD-ROM drive.

In Program Manager, choose Run from the File menu.

In the Run dialog box, type cd_driveletter:\Exchange\<operating system\platform>Modeling\Domplan\Setup, and then choose OK. Running this file copies the required files into your systemroot\WinNT\System32 directory.

Follow the instructions on the screen to complete Setup.

Setup creates a program group for the Windows NT Domain Planner. For more information, choose Help in the Windows NT Domain Planner.

To install the Microsoft Mail Export / Import Tool:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can also be installed directly from the BackOffice Resource Kit Part Two Setup.

Or use the Setup program in \Exchange\<operating system\platform>\Admin\Eximwiz2 to set up this program. See Exchtool.hlp for setup information.

To install the Natural Language Support Configuration Tool:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can also be installed directly from the BackOffice Resource Kit Part Two Setup.

Or use the Setup program in \Exchange\common\NLS to set up this program. See Exchtool.hlp for setup information.

To install the Microsoft Exchange Preview Pane Client Extension:

Start Windows 95 or Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

Type cd_driveletter: msetup, then choose OK.

From the Microsoft BackOffice Resource Kit screen, click More MS Exchange Tools.

Click the tool you wish to install.

Follow the instructions on the screen to complete Setup.

This tool can also be installed directly from the BackOffice Resource Kit Part Two Setup.

Or you can install the Microsoft Exchange Client Preview Pane Extension on any supported platform by copying the \\Exchange\<operating system\platform>\Client\Tripane files to a temporary directory and running Setup.

To install the Profgen Tool:

Follow the setup instructions in the Exchtool.hlp Help file.

To install the Simple Mail Handler Tool:

For all operating systems except Windows NT Workstation, copy Mergeini.exe and the DLL for your operating system to the \Windows\System directory. For Windows NT Workstation, copy Mergeini.exe and the DLL to the system32 directory.

Run the Mergeini.exe tool to add the Simple Mail Handler to the list of services available.

In Control Panel, choose Mail and Fax.

Select the Services tab, and then choose Add.

Select Sample Mail Handler, and then choose OK.

To install Microsoft Exchange Server Tools for the Power PC Platforms

The following Microsoft Exchange Server tools are available for Power PC Platform. To install these tools, follow the setup instructions in the Exchtool.hlp Help file.

ASpiriN

Buddy Dropper

Global Send Options

Mailstorm

Public Folders Tree Info

Sentinel

SMH

1.3.3 Additional Setup Information on SNA Server Tools

APPCTest is not installed during installation of the BackOffice Resource Kit. The following instructions will install a working copy of APPCTest.

To install APPCTest:

APPCTest is installed as a separate utility. The following instructions will install a working copy of APPCTest:

Start the BackOffice Resource Kit from the CD-ROM.

On the welcome screen, locate "Interactive APPC Test Tool" and click on the title.

Follow the dialog box prompts to complete installation.


1.4 TechNet

To set up the BackOffice TechNet:

Start Windows NT and insert the Microsoft BackOffice Resource Kit: Part Two CD-ROM in the CD-ROM drive.

In Program Manager, choose Run from the File menu.

In the Run dialog box, type cd_driveletter:\Apps\Technet\Setup, and then choose OK.

Follow the instructions on the screen to complete Setup.


2.0 User Notes


2.1 Microsoft Systems Management Server Tool Notes

The tools provided for use with Microsoft Systems Management Server are intended for use with Systems Management Server 1.2 only.

The binaries for the SMS New Service Account utility (Newsvcac.exe) are not on the BackOffice Resource Kit Part II CD-ROM. At the time of shipping, this application was undergoing burn-in testing. If the tests are successful, it is intended that the binaries will be placed on the FTP site for the BackOffice Resource Kit: ftp://ftp.microsoft.com/bussys/backoffice/reskit/.

2.1.1 Windows NT Inventory File Collection Tool

In the Installation program for the Windows NT Inventory File Collector (Instpoll.exe), the default path contains spaces. Delete the spaces before continuing. Also, the installation program exits without confirming that installation is complete.

In the Password dialog box of the Windows NT Inventory File Collector installation, the OK button is not the default pushbutton, so pressing ENTER does not close the dialog box.

If you enter a bad service account during the installation of the Windows NT Inventory File Collector service, you will not be notified, although a log file called Pollreg.log will be created. However, when you try to start the service, it won't start. The service account must be given as the domain and the username in the form DOMAIN\username.

2.1.2 Srvinfo Tool

The Srvinfo tool is not supported for the Alpha platform running Windows NT 3.51.

2.1.3 SHRPERM.EXE

When SHRPERM sets share permissions on Windows NT Server or Windows NT Workstation, it overwrites the existing permissions. It does not modify the existing permissions. The folder must already be shared when you use SHRPERM.EXE to change the permissions.

2.1.4 Controlling Secondary Site Upgrades

Typically, when a new version of Systems Management Server is installed at the primary site, the secondary sites reporting to the primary are automatically updated to this new version. In some cases you may want to block the automatic upgrade of secondary sites, and upgrade them manually after the primary site has been upgraded. Tools and documentation to do so are included with this Resource Kit. For details, see Upg2site.doc in the SMS\Docs directory on the BackOffice Resource Kit CD-ROM.

The documentation and tools for controlling secondary site upgrades are also available at http://www.microsoft.com/SMSMGMT/whitepaper.htm.

Note The tool for performing manual upgrades to secondary sites must be run from the directory in which the DLLs are located: SMS\SITE.SRV\platform.BIN.

When typing the command

setup /SYSMAP:system_map_path\SYSTEM.MAP /NOAUTOUPGRADE

great care must be taken not to misspell any of the parameters. A misspelled parameter will not be reported, and could cause the setup to unintentionally upgrade the secondary sites. To avoid this, use

setup2 path

where path is the fully qualified path to the new SYSTEM.MAP file. The setup2.cmd script will always print the usage information whether or not the correct path is entered.

The Setup.exe utility requires the following DLLs:

Ntwdblib.dll

Msvcrt40.dll

Dbnmpntw.dll

2.1.5 Location of the SMSSAFE.TMP file

As documented in the BackOffice Resource Kit Part I, the SMSSAFE.TMP file is created by the Inventory Agent to record the status of hardware inventory. This file is located in drive_letter:\ms\sms\data, not in the root directory of drive_letter.

2.1.6 CHKSMS.SQL

In the BackOffice Resource Kit Help and in Chapter 4, "Tools," of the Microsoft Systems Management Server Resource Guide, there are references to a file named CHECKSMS.SQL. The file name should be CHKSMS.SQL.

2.1.7 Replicating MSTEST Files Down a Hierarchy

In the BackOffice Resource Kit Help and in Chapter 4, "Tools," of the Microsoft Systems Management Server Resource Guide, under the topic "COPYVT.BAT," an example is presented as instruction, and could be confusing. It is more accurate with the following change:

Because the mstest files are not automatically replicated down a hierarchy, you must copy them to every site that needs them. The platform of the files to copy to a current site should be the same as the platform of the clients that will use them; it does not depend on the platform of the current site. For example, you could copy the x86 files to the site and use them to install all the x86 sites you want. Then copy the Alpha files to the site (overwriting the x86 files) and use them to install all the Alpha sites you want. An Alpha client must find the Alpha files on its site server, even if its site server is x86.

2.1.8 CLIOPTS.EXE

CLIOPTS.EXE is a 16-bit application. It applies only to Windows 3.1 and Windows for Workgroups clients.

2.1.9 FILEMOVE Utility

Target Directories Must Already Exist

When you use FILEMOVE to copy files, the target directories must already exist. If you attempt to copy files to a non-existent directory, the files will not be copied. The reported number of files copied will reflect that files were not copied to the non-existent directory, but no error message is generated.

Polling Interval Setting

If the polling interval in the FMUI dialog box is missing or invalid, you will be prompted for the polling value and the value for the polling interval and for the log file size will be set to 0. You must then enter a valid integer for both of these fields.

Log File

The size of the log file for the FILEMOVE utility must be explicitly set. If no value is set for the log file size, you will be prompted for the log file size (in kB). The log size must be set to an integer value between 10 and 100000000. Be sure the value you supply is within this range. If you specify a value greater than 100000000, the invalid value appears to be accepted but the file size remains at the last valid value.If you specify a value less than 10, you will be prompted for a valid value, and the values for both the polling interval and the log file size will be set to 0. You must then enter a valid integer for both of these fields.

As described in the BackOffice Resource Kit Help and in Chapter 4, "Tools," of the Microsoft Systems Management Server Resource Guide, FILEMOVE.EXE writes status to its log file (FILEMOVE.LOG). When this log file reaches its maximum size, it is closed and renamed FILEMOVE.LO_. A new FILEMOVE.LOG file is then created. Note that if an earlier FILEMOVE.LO_ file exists, it is overwritten by the new FILEMOVE.LO_ file.

Make sure you have sufficient space for the files to be copied and for the log file on the target computer. If the drive containing the log file becomes filled while the log file is smaller than the maximum size you have set, FILEMOVE will be unable to append new logs to the file. In this case the log file never reaches its maximum size, and so the FILEMOVE.LO_ file is never created or overwritten. As a result you have an incomplete log. If the drive that FILEMOVE attempted to copy files to was also filled, some of the lost entries will concern files that were not successfully copied.

Polling Interval and Creation of New Folders

If a folder is being created on the target computer when the polling for FILEMOVE begins, the process that is creating the folder will hang until FILEMOVE.EXE or the FILEMOVE service is stopped, and some of the information supplied to create the folder may be lost. (For example, the last one or two characters of the folder name might be lost.) You may want to set the polling interval so that polling is unlikely to begin at times when a folder may be being created.

2.1.10 Creating a UMF File

The Reskit utiltity UGMIF.EXE creates a user group MIF file with a .MIF extension. As of SMS 1.2, user group MIF's should have an extension of .UMF. After you have created the user group MIF file with UGMIF.EXE, the MIFNAME tool can be used to rename the MIF file to a UMF file.

2.1.11 Notes on PDFWIZ.EXE

The following notes apply to the PDF Wizard (PDFWIZ.EXE).

Specifying Windows NT ALPHA

The PDF Wizard (PDFWIZ.EXE) does not successfully specify WindowsNT (ALPHA) as an operating system on which the files can be installed or deinstalled. This setting must be adjusted manually after the PDF is imported into SMS.

Selecting Platforms On Which Files Can Be Installed

The dialog in which you specify the platforms on which the files in the PDF can be installed is the tenth dialog. It is mis-labeled Select the operating system on which the deinstallation command can run.

2.1.12 Notes on RSERVICE.EXE

The following notes apply to the new features of RSERVICE included in this Resource Kit.

Path Must Exist for Files in [other files] Section of Initialization File

The files listed in the [other files] section of the RSERVICE initialization file will be installed successfully if and only if the directory specified for those files exists on the destination computer. Make sure that all directories in the path have been created before using RSERVICE to install the service.

Path Must Exist for Log Files

When you use the /log option to the rservice command, a log file will be created if and only if the directory specified with the /log option exists.

Using the /deinstall Parameter

When you remove a service using the rservice /deinstall command, the user account specified in the [service account] section of the RSERVICE initialization file is removed from Administrators local group on the client computer. However, the account still exists in the domain, and it still has the log on as a service privilege on the client computer. You may want to explicitly change the permissions for the user account on the client computers.

Do Not Use The /change Parameter

The /change parameter to the rservice command does not successfully change the service account or password. If you accidentally use this parameter, you may be unable to start the service using either the old or the new account and password. If this happens, remove and reinstall the service.

Computer Prefixes In [automatic start] and [machine list] Sections

In the [automatic start] section of the RSERVICE initialization file, list the computername for each computer, or indicate all computers with the *=parameter entry. Do not use computer prefixes in this section.

In the [machine list] section of the RSERVICE initialization file, list the computername for each computer. Do not use computer prefixes in this section.

Permissions For Files in [other files] Section of Initialization File

The permissions specified in the [access permissions] section of the initialization file are assigned to those files listed in the [other files] section that are installed in the directory specified in the [installation directory] section. Files that are installed in other directories will not be assigned the permissions specified in the [access permissions] section.

Embedded Spaces

Rservice will not accept embedded space characters in the Registry Keys, values or paths secified in the Iinitialization file. An embedded space will cause the file to be parsed incorrectly.

2.1.13 Notes on PCM as a Service

Note that the PCM service must have all needed programs in the package source. The PCM service will not find files located in the MSTEST directory. This means NTENCAP.EXE must be copied to the package source, along with any special files such as the NTUPGRD.SCR or NTUPGRD.400 script files.

PCM Service Log File

In rare cases, on computers running WindowsNT, the PCM service does not produce a log file as expected. If this happens, set a log file name using a relative path (rather than an absolute path). The log file will then appear in the winnt\system32 directory on the boot drive.

2.1.14 SVCCTRL.EXE

The Service Control utility (SVCCTRL.EXE, formerly called INSTSRV.EXE) controls services using the name used in the registry, rather than the "display name" that appears in dialog boxes. In most cases, these names are identical. The names are most likely to differ when there are spaces in the display name (for example, SMS Client Inventory and SMS Remote Control Agent).

If SVCCTRL seems unable to control a service, check for the name used for the service in the registry. You can either examine the registry directly, or use TLIST.EXE (included in the BackOffice Resource Kit) to view a list of the names of executable files that are running, and cross the executable name to the display name. When looking for information in the registry, if it is in a key, use \View \Find Key… , unselect "match whole word only", enter the string and search. The key for WUSER32 can be found by searching for wuser. If the information is in a value, use \Registry \Save subtree as … to save the registry to a text file, open the file in notepad (the registry can be several megs in size so this can take a while), and use find in notepad to search for the value. The display name is a value, so this is the way that a display name will have to be crossed if it is not listed in the cross reference. Most tools controlling services can only use the service name, or executable name, not the display name.

Service Name | Display Name
WUSER32 | SMS Remote Control Agent
INV32CLI | SMS Client Inventory

2.1.15 NetBoot Help - "About NetBoot"

The "About NetBoot" dialog in the Help for NetBoot is not accessible after the utility has been used to create a net boot disk. The "About NetBoot" dialog becomes available again after you close and re-open the utility.

2.1.16 SKIPINV.EXE

In the example given for SKIPINV in the BackOffice Resource Kit Help and in Chapter 4, "Tools," of the Microsoft Systems Management Server Resource Guide, the line

if errorlevel 12 goto RESTORE

should be changed to

if errorlevel 12 goto SCAN

2.1.17 Network Boot Floppy

Netboot.exe requires that a database engine, such as Microsoft Access 7 (Access 95), be installed and available to the Netboot utility. Netboot.exe will not work with Microsoft Access 2 or Access 8 (Access 97).


2.2 Microsoft Exchange Server Tool Notes

2.2.1 Profile Generator

The Profile Generator tool has been revised and is located in \Exchange\<operating system\platform>\Admin\Profgen. Since the program has no user interface, the version number is only available through the log file generated by the program. Whats new in this version:

Added the -R option (DonotRenamePRF INI file entry).

This controls whether or not the PRF file is renamed at the end of the program

Added the -N (UserLoginIDAsProfileName INI file entry).

This controls whether or not the profile is created with Current NT login ID as the name of the profile.

Added the -T option (TempFilePath INI entry) to specify the location of the profgen.tmp file.

Added support for the -I command line option, to specify the mailbox to use from the command line.

Useful when running from login scripts.

If the -I option is specified with a mailbox name, then the program does not use the API call to determine what the current login ID is.

2.2.2 SMTP Proxy Migration Tool (Migsmtp.exe)

You should stop the DXA service while running Migsmtp.exe. After you do so, be aware that synchronization won't occur until the next scheduled time.

2.2.3 Addition to the Microsoft Exchanger Server Resource Guide

A new registry entry has been added for the Microsoft Mail Interchange (MSMI) that is not documented in Chapter 6 of the Microsoft Exchange Server Resource Guide.

Registry path:

\HKEY_LOCAL_MACHINE
\SYSTEM
\CurrentControlSet
\Services
\MSExchangeMSMI
\Parameters

Value Entry: | Pass SMTP headers to SFS
Data Type: | REG_DWORD
Range: | 0 | 1
Default: | 0

Value | Meaning
0 | The Exchange MS Mail Connector sends SMTP headers to MS Mail SFS clients.
1 | The Exchange MS Mail Connector does not send SMTP headers to MS Mail SFS clients.

This value entry specifies whether or not SMTP headers are sent to MS Mail SFS clients by the Exchange MS Mail Connector. The effect of this value entry is different depending upon which mail client (MS Mail or Exchange) receives and displays the mail, whether or not the the sender is defined as a custom recipient in Exchange, whether the message is of class MAPI, and upon the status of the StripGatewayHeaders value entry that can be set by the Windows MS Mail client.

These variables determine whether or not the SMTP headers are received and displayed by SFS. The SMTP headers may not be displayed by the MS Mail Client, even if the Pass SMTP Headers to SFS value entry has the default value of 0.

When SFS receives a message from the Internet Mail Service and the sender of the message is defined as a custom recipient in Exchange, the MS Mail Windows Client will always display the message headers. If the StripGatewayHeaders value entry is set, it is over-ridden by these circumstances. This happens because although the MS Mail Client is aware of message header information in addition to the MAPI designation, it is unable to parse the additional fields and so the client displays all header information, regardless of its type. This is default behavior of the MS Mail Client.

When SFS receives a message from the Internet Mail Service and the sender of the message is not a custom recipient in Exchange, but has an address of type MS:\net\po\user, the MS Mail Windows Client and the MS Mail Transport Service for Exchange will never display the message headers. In this case, if the StripGatewayHeaders value entry is set to display header information, and the Pass SMTP Headers to SFS value entry is set to 0, the MS Mail Windows Client and the MS Mail Transport Service for Exchange will still be unable to display this information. This is also MS Mail Client default behavior.


2.3 Microsoft SQL Server Tool Notes

The Microsoft SQL Server Resource Guide and Help file are up-to-date. No additional changes are documented in these release notes.

2.3.1 Arcadia Bay Demonstration

The Arcadia Bay demonstration on the BackOffice Resource Kit CD-ROM is a self-extracting ZIP file. The Arcadia Bay files will be extracted into the Bork\Sql\Arcadia directory when the ZIP file is opened.

2.3.2 SQL Trend Analyzer

The SQL Trend Analyzer tool on the BackOffice Resource Kit CD-ROM is a self-extracting ZIP file. The SQL Trend Analyzer files will be extracted into the Bork\Sql\SQLTrend directory when the ZIP file is opened.


2.4 Microsoft SNA Server Tool Notes

The Microsoft SNA Server Resource Guide is up-to-date. One change to the SNA Server Help file is described in section 2.5.3.


2.5 Help File Corrections

2.5.1 Corrections to Smstools.hlp

Note the following changes to the Smstools.hlp file:

In the description of CHECKRAS.EXE:

The first sentence of the description should change to "Checkras is run on an SMS client, and indicates whether it is connected to a server using the Remote Access Service (RAS)."

In the description of rservice:

The following Note appears in Help for rservice:

Note If the path to the initialization file is incorrect, you will get the following message: The domain is not specified in the [DOMAIN NAME] section of INI file .\test.ini.

This note no longer applies.

In the section on using SKIPINV.EXE:

For more reliable operation, SKIPINV.EXE should be run from the client rather than from the server. In the example script, both instances of the line

%0\..\skipinv.exe

should be replaced by

xcopy skipinv.exe c:\

c:\skipinv.exe

In the description of SMS_NT_INVENTORY_FILE_COLLECTOR:

This tool runs only on the x86 platform. The section on "Installing the inventory file collector on ALPHA computers" should be disregarded.

In the description of files required for TRACER.EXE:

Disregard the comments in the Files Required section.

In the description of UGMIF.EXE:

Under Files Required, the final sentence should read "This tool must run from the directory in which the DLLs are located: SMS\SITE.SRV\platform.bin."

In the syntax description of UGMIF.EXE:

The /t option description should be "includes domains that trust the domain in which UGMIF.EXE is executed in" The /d:domain description should be "Specifies a Windows NT domain. User groups will be listed from this domain. If /t is also used with this switch, user groups from all domains trusting this domain will also be listed."

2.5.2 Corrections to Exchtool.hlp

Corrections and Additions to Help Information on the Buddy Dropper Tool

Troubleshooting

Error Message: Buddy Dropper Remote tool: ERROR 10048: Unable to create server socket.

This error is displayed if another application is already using Dropper Remote's Winsock socket. Use Task Manager to verify that there is no DROPRM.EXE already running. If only one instance of Droprm.exe is running, another custom WinSock application may be running. Turn off this application while Droprm.exe is running.

Corrections to Help Information on the Mailbox Cleanup Agent

The tool location is listed incorrectly in the exchtool.hlp and tools.doc files as the

Exchange\<operating system\platform>\Security\Keytoken subdirectory on the Microsoft BackOffice Resource Kit, Part Two CD-ROM. The correct location is the Exchange\<operating system\platform>\Admin\MBClean subdirectory on the Microsoft BackOffice Resource Kit, Part Two CD-ROM.

Corrections to Help Information on the Mailbox Migration Tool

The Control File fields are abbreviated in error in the exchtool.hlp and tools.doc files. The correct Control File fields are listed in the table below. A sample control file (sample.csv) is included in the Exchange\Winnt\<platform>\Admin\MBMigrate directory on the Microsoft BackOffice Resource Kit: Part Two CD-ROM.

Incorrect | Correct
Control File Field | Control File Field
SrcOrgName | Source Organization Name
SrcSiteName | Source Site Name
SrcAliasName | Source Alias
DisplayName | Source Display Name
SrcNewDisplayName | Source New Display Name
SourceServer | Source Server Name
DestOrgName | Destination Organization Name
DestSiteName | Destination Site Name
DestAliasName | Destination Alias
DestNewDisplayName | Destination New Display Name
DestinationServer | Destination Server
PstUNCName | PST Locations
PstBackup | PST Backup Flag
SetupAutoRules | Setup Auto Rules
DoSentDeletedItems | Copy Sent/Deleted Items Flag
Status | Status
Description | Description
TimeStamp | TimeStamp

Corrections and Additions to Help Information on the ASpiriN Tool

In the description of ASpiriN:

"The ASpiriN tool enables you to conveniently view and browse X400 ASN.1 data by using the ASN.1 X400 templates from the Microsoft Exchange Server message transfer agent (MTA)."

should read:

The ASpiriN tool allows you to decode and interpret X.409 ASN.1 (Abstract Syntax Notation 1) data. ASN.1 is a language for describing structured information. In Exchange, the Exchange Message Transfer Agent (MTA) transmits P1 envelope and sometimes P2 content data in ASN.1 format. This tool can be used to decode or interpret ASN.1 data much like our Exchange MTA would decode and interpret the data. ASpiriN supports P1, P2, and P772 data.

Additional ASpiriN Help File Information

The following sections should have appeared in the ASpiriN Help File.

To install ASpiriN

From the Exchange\<operating system\platform>\Admin\ASpiriN directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy ASpiriN.exe to your computer.

Using ASpiriN

To run ASpiriN:

From the Start menu, choose Run, and then choose Browse to search for the folder or subdirectory where you copied the file.

Select the ASpiriN folder, and then select ASpiriN.exe.

To open a hexadecimal or binary-format ASN.1 file:

From the File menu, choose Open.

Select Hex if the file contains ASN.1 data encoded as hexadecimal ASCII.

Select Binary if the file contains ASN.1 data encoded as raw binary.

To produce ASN.1 data files from a Microsoft Exchange Server MTA log file:

The Microsoft Exchange MTA logs messages and other information in the Exchsrvr\Mtadata directory as BF*.log files. These files contain, among other pieces of data, ASN.1 hexadecimal dumps of messages passing through the MTA. These ASN.1 blocks can be viewed by using ASpiriN if they are parsed out of a BF*.log file.

To view ASN.1 blocks:

From the File menu, choose Parse MTA Log.

Select a log file, such as Bfo.log, and then choose OK.

After you follow these steps, ASpiriN produces one hexadecimal file in the same directory as the log file for each block in the log file. Some, but not all blocks, are ASN.1 data. You can view the ASN.1 hex files by following the procedure outlined earlier.

Note Not all references obtained from the BF*.log file are ASN.1. If they are not ASN.1 ASpiriN will pop up a warning that says:

ERROR: HRESULT=0xe0010004; Cannot identify beginning type. Decoding stopped at offset 0

If the offset says 0, the reference in the BF*.log was not ASN.1. This is not a bug. If the offset was not zero, then part of the ASN.1 was parsable, and there were some problems. Offsets past offset 0 are potential interoperability problems and may warrant reporting to Product Support.

These warnings, as described above, point out places where the ASN.1 interpreter did not understand some of the data, and point out potential interoperability problems with other MTAs. Please report errors to Product Support of the type:

WARNING: Unknown Type encountered at offset 465. Basic Encoding Rules will be used for this type and its children

When reporting problems concerning ASpiriN.exe such as Feature requests, bug reports, etc.

Please include the following:

Exchange MTA version number

ASpiriN.exe version number

Foreign MTA (if appropriate) and vendor and version number.

A detailed description of the problem or request

The .hex or .bin ASN.1 file or the BF*.log with problem

Troubleshooting ASpiriN

If you have problems during ASN.1 decoding, a message should appear describing the problem. If applicable, you are prompted to choose whether you want the decoder to attempt to continue. Continuing does not guarantee that the decoding will be successful.

If a decoder error is produced, verify that:

You have access permissions on the ASN.1 data file

The selected file is actually ASN.1 data

You chose the correct data format (hexadecimal or binary). If one format didn't work, try the other.

If you have problems parsing an MTA BF*.log file, verify that:

You have permissions to create files in the BF*.log's directory.

You have disk space available to create additional files.

The log file is not obviously corrupted.

The log file is not empty.

Corrections and Additions to Help Information on the Duplicate Proxy Search Tool

The directory names are listed incorrectly in the Help file. The help file should read:

To install the Duplicate Proxy tool

From the Exchange\<operating system\platform>\Admin\Dupproxy directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Dupproxy.exe to your computer. From the Libs directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Wldap32.dll to the \Windows\System directory for Windows 95 or for Windows NT, copy Mergeini.exe and the DLL to the system32 directory.

Corrections and Additions to Help Information on the Pkicker Tool

The directory names are listed incorrectly in the help file. The help file should read:

To install the PKicker tool

From the <operating system\platform>\Admin\Pkicker subdirectory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Pkicker .exe to your computer. From the Libs directory on the Microsoft BackOffice Resource Kit, Part Two compact disc, copy Rpcdce4.dll to the \Windows\System directory for Windows 95 or for Windows NT, copy Mergeini.exe and the DLL to the system32 directory.

Using the Pkicker tool

When the tool is sucessfully run, the message "Passed:" is displayed. This message notifies the user the tool is working correctly and that the proxy modification has been initiated.

Warning It is possible to remove X400 proxies with the Pkicker tool. If you inadvertently remove a proxy, you can regenerate them by using the following command line.

pkicker /Fadd /Tx400 where T = proxy type

Corrections to Help Information on the PF Admin Tool

The command line usage help (pfadmin ?) incorrectly states that there is additional help for sections LISTACL and LISTREPLICAS.

Warning Use the REHOME command with caution! The REHOME comand deletes the existing Replica list and sets it to the server where the folder is being re-homed. The previous Replica list will be lost. The REHOME option is equivalent to SETREPLICAS with a single replica specified.

Corrections and Additions to Help Information on the Inetxidm Tool

The Internet Idioms Tool requires Microsoft Windows 95 or Windows NT 4.0 with the Microsoft Exchange Client installed. It will not work on Windows NT 3.51. Internet Idioms does not support Microsoft Outlook 97, Microsoft Office WordMail, or Microsoft Office 97 WordMail.

When you first start your mail client after installing the Inetxidm tool, you may get the following message:

"You are starting a version of Exchange (or Windows Messaging) that postdates the last version officially tested with Internet Idioms. Do you wish to load Internet Idioms?"

Click yes to disable this message in the future. If you do not with to run Internet Idioms, Exit and log out of Exchange. Run regedit, open the key

HKEY_LOCAL_MACHINE\Software
\Microsoft
\Exchange
\Client
\Extensions

and delete the "Internet Idioms" registry entry and its value. Delete the file inetxidm.dll from your computer.

Internet Idioms will not work with the simplified send note included in the Windows 95 Messaging Update. This will prevent Idioms from appending signatures to messages sent through Internet Explorer mailto: references unless you clear Tools - Options - Send - Use simplified send note to disable this feature.

If you read messages routed through the Microsoft Exchange Serve Internet Mail Service, Idioms cannot change the read font.

2.5.3 Correction to SNAtools.hlp

The online help file for SNATALK states that "Banyan VINES requires the VNSAPI32.DLL." The DLL is delivered with the Banyan VINES Enterprise Client. It is SNATALK.EXE that requires this DLL to run properly.


3.0 Other Online Documents

The following table describes other online documents that contain important information about files available on the Microsoft BackOffice Resource Kit: Part Two CD-ROM.

Document | Directory | Description
Borktool.hlp | Help | Help file that accesses the Microsoft Exchange Server Tools Help, the Microsoft Systems Management Server Tools Help, the Microsoft SQL Server Help, and Microsoft SNA Server Help.
Eperfmon.hlp | Exchange\Docs | Help for the Windows NT Performance Monitor Counters for Microsoft Exchange Server.
Exchtool.hlp | Exchange\Docs | Help for the Microsoft Exchange Server and Microsoft Exchange Client tools on the CD-ROM.
Exmsgref.hlp | Exchange\Docs | Help guide to the error messages generated by Microsoft Exchange.
Fmui.hlp | SMS\Docs | Help for the FMUI.EXE tool
Netboot.hlp | Sms\Netboot | Help for the NetBoot Administrator.
Selfcert.wri | Exchange\Docs | Information on using the form in Selfcert.doc.
Selfcert.doc | Exchange\Docs | Self-certification form for temporary export of encryption software.
Smsaddin.hlp | Sms\Docs | Help for Console Application Integration.
Smgenie.hlp | SMS\Docs | Help for the SMS Event Generator tool.
Smstools.hlp | SMS\Docs | Help for the Microsoft Systems Management Server tools on the CD-ROM.
Splusdk.hlp | Exchange\Docs | Microsoft Schedule+ Programmer's Reference Help file
Upg2site.doc | SMS\Docs | Document on controlling secondary site upgrades


4.0 Resource Kit Support Policy

The software supplied on the Microsoft BackOffice Resource Kit: Part Two CD-ROM is not officially supported. Microsoft does not guarantee the performance of the Microsoft BackOffice Resource Kit: Part Two tools, response times for answering questions, or bug fixes to the tools. However, we do provide a way for customers who purchase the Microsoft BackOffice Resource Kit: Part Two to report bugs and receive possible fixes for their issues by either sending Internet e-mail to rkinput@microsoft.com or by referring to one of the options listed in the "Your Guide to Service and Support" pamphlet, which is included with your Windows NT product. This e-mail address is only for Microsoft BackOffice Resource Kit: Part Two-related issues.

The software (including instructions for its use and all printed and online documentation) is provided "AS IS" without warranty of any kind. Microsoft further disclaims all implied warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The entire risk arising out of the use or performance of the software and documentation remains with you.

In no event shall Microsoft, its authors, or anyone else involved in the creation, production, or delivery of the software be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the software or documentation, even if Microsoft has been advised of the possibility of such damages.


5.0 File List for the Microsoft BackOffice Resource Kit: Part Two CD-ROM

The following is a list of the tools included on the Microsoft BackOffice Resource Kit: Part Two CD-ROM. For more information on them, refer to the Borktool.hlp Help file. The following section contains a list of the Microsoft BackOffice Resource Kit: Part Two CD-ROM directory structure.


5.1 Microsoft BackOffice Resource Kit File List

In the root directory:

setup.exe | Setup for tools on the Microsoft BackOffice Resource Kit: Part Two CD-ROM
autorun.inf |
bork.inf |
setup.ini |
setup.lst |
setup.tdf |
readme.wri | This Readme file

In the \APPS\IIS301A\i386 and the \APPS\IIS301A\ALPHA directories:

The Microsoft Internet Information Server for the Intel and Alpha plaforms.

ASP.EXE

In the \APPS\TECHNET directory:

Microsoft TechNet for the Microsoft BackOffice Resource Kit, February 1997. TechNet can be installed by running Setup.Exe from the \APPS\TECHNET directory of the Microsoft BackOffice Resource Kit: Part Two CD-ROM.


5.2 Microsoft Systems Management Server File List

In the Sms\Docs directory:

Fmui.hlp | Help file for Fmui.exe and Filemove.exe (new)
Fmui.cnt | Contents file for Fmui.hlp (new)
Upg2site.doc | Whitepaper describing how to manually upgrade secondary sites from SMS 1.1 to SMS 1.2 (new)
Smgenie.hlp | Help file for Smgenie.exe
Smsaddin.hlp | Help file for Smsaddin.exe
Smsaddin.cnt | Contents file for Smsaddin Help
Smstools.hlp | Master help file for the SMS utilities
Smstools.cnt | Contents file for Smstools.hlp

In the Sms\Bins\I386 and Sms\Bins\Alpha directories:

Acctchg.exe | SQL account change tool (command-line tool)
Breakftm.exe | Mirror-breaking tool (command-line tool)
Breakftm.pdf | Package Definition File for using Breakftm.exe
Bugdata.exe | Collects debug information into a single file (command-line tool)
Checkras.exe | Indicates number of RAS connections (command-line tool)
Chksms.sql | SQL script
Delmif.exe | Creates a MIF to delete a machine (command-line tool)
Delmif.dll | DLL required for Delmif.exe
Dumpsend.exe | Displays contents of a send request file (command-line tool)
Dumpsync.exe | Cleans RESYNC.CFG files (command-line tool)
Error32.exe | Displays textual error message for given error code (command-line tool)
Filemove.exe | Service which moves or copies files from one specified direcory to another, parameters are set using FMUI.EXE (new) (I386 only)
Filetokn.exe | Outputs attribute information for a file (command-line tool)
Fiperf.bat | Install script for the SMS_FILES perfmon counter (can be removed after installing the counter)
Fmui.exe | GUI application for setting the parameters for FILEMOVE.EXE (new) (I386 only)
Miperf.bat | Install script for the SMS_MIFS perfmon counter (can be removed after installing the counter)
Fiperf.dll | DLL that perfmon calls to report SMS_FILES counter
Miperf.dll | DLL that perfmon calls to report SMS_MIFS counter
Fictrnm.h | Required for installing the SMS_FILES perfmon counter (can be removed after installing the counter)
Mictrnm.h | Required for installing the SMS_MIFS perfmon counter (can be removed after installing the counter)
Fi.ini | Required for installing the SMS_FILES perfmon counter (can be removed after installing the counter)
Mi.ini | Required for installing the SMS_FILES perfmon counter (can be removed after installing the counter)
Hcomp.exe | File compression tool (command-line tool)
Hdecomp.exe | File decompression tool (command-line tool)
Hvalcomp.exe | Compressed file validation tool (command-line tool)
Mifcheck.exe | Checks syntax of a .MIF file (command-line tool)
Mifname.exe | Renames SMS 1.1 MIF files (command-line tool)
Nadreset.bat | Cleans out NAD entries on a client (command-line tool)
Nwattrib.exe | Sets attributes of NetWare files (command-line tool)
Pcmdump.exe | Dumps contents of PCM instruction file (command-line tool)
Pdfwiz.exe | Windows wizard tool for generating PDFs.
Pdfile.dll | DLL required for Pdfwiz.exe
Pgcset32.exe | Sets the PGC status (command-line tool)
Rawcheck.exe | Checks syntax of a .raw file (command-line tool)
Reglist.exe | Dumps registry information (command-line tool)
Rsappctl.exe | Resets shared application database of child sites (command-line tool)
Rservice.exe | Remotely start/stop a service (command-line tool)
Sendcode.exe | Sends control codes to Systems Management Server Services (command-line tool)
Setclcfg.exe | Forces a client to install Client Configuration Services, or changes Client Services (command-line tool)
Setgug.exe | Sets the Global User Group reporting interval (command-line tool)
Shrperm.exe | Sets share permissions (command-line tool)
Smgenie.exe | Generates Windows NT Events
Smsaddin.exe | Tool to register tools into the Tools AddIns menu in the Systems Management Server Administrator Window.
Smsperfr.dll | DLL used by SMS_FILES and SMS_MIFS containing resource strings
Smstrace.exe | Traces Systems Management Server .log files
Smstrace.atd | Configuration file to add Smstrace to the Tools AddIns menu. Run Smsaddin Smstrace.atd from the command line.
Smsmaint.sql | SQL script
Sqlpwd.exe | Changes SQL password (command-line tool)
Srvinfo.exe | Displays information about local or remote computer. Version for Windows NT 4.0 (command-line tool)
Svcctrl.exe | Interactive Service install tool (command-line tool)
Testnet.exe | Diagnoses network and name resolution problems (command-line tool)
Tracer.exe | Traces Systems Management Server .log files (command-line tool)
Tracer.dll | DLL required for Tracer.exe
Ugmif.exe | Creates Global User Group MIF (command-line tool)
Viewnad.exe | Displays applications and servers available to a client (command-line tool)
Writepdf.exe | Writes a PDF file from a package in the database (command-line tool)
Writeqdf.exe | Reads or writes a query definition file into or from the database (command-line tool)
Zap.exe | Deletes a file, even if it is being accessed (command-line tool)

In the Sms\Bins\I386\Nt351 and Sms\Bins\Alpha\Nt351 directories:

Tlist.exe | Displays process list. Version for Windows NT 3.51 (command-line tool)
Kill.exe | Kills a running process. Version for Windows NT 3.51 (command-line tool)
Regini.exe | Initializes registry. Version for Windows NT 3.51 (command-line tool)
Srvinfo.exe | Displays information about local or remote computer. Version for Windows NT 3.51 (command-line tool, i386 only)

In the Sms\Bins\I386\Nt40 and Sms\Bins\Alpha\Nt40 directories:

Tlist.exe | Displays process list. Version for Windows NT 4.0 (command-line tool)
Kill.exe | Kills a running process. Version for Windows NT 4.0 (command-line tool)
Regini.exe | Initializes registry. Version for Windows NT 4.0 (command-line tool)
Srvinfo.exe | Displays information about local or remote computer. Version for Windows NT 4.0 (command-line tool)

In the Sms\Clients\Win16 directory:

Assetmif.exe | Collects extra asset information from clients
Assetmif.ini | File containing asset information for Assetmif.exe
Badpent.exe | Detects if the Pentium FPU error is present (command-line tool)
Badpent.pdf | Package Definition File for distributing Badpent.exe
Cliopts.exe | Controls the client's transport protocol used for Help Desk activities. Command-line tool
Ferret.exe | Reports extra asset information on Compaq computers (command-line tool)
Ferret.pdf | Package Definition File for distributing Ferret.exe
Cpqbssa.txt | Data file used by Ferret.exe
Ismif16.exe | Generates a generic Status MIF
Naduser.exe | Indicated User Global Group membership and available applications on a client.
Remfprot.exe | Removes 16-bit F-Prot from Config.sys
Skipinv.exe | Checks if client inventory needs to be performed (new)

In the Sms\Clients\I386 and Sms\Clients\Alpha directories:

Isidis.exe | Checks if Idis_NT.dll installed (command-line tool)
Ismif32.exe | Generates a generic Status MIF

In the Sms\Queries directory (new):

See the Systems Management Server Resource Guide Supplement, Chapter 1 for instructions on how to use the files in this directory.

Off97rdy.qdf | SQL query to determine which clients are in a state where Office97 can be installed. Use WRITEQDF.EXE to read the query into SMS
Offpro97.qdf | SQL query to determine which clients have Office97 installed. Use WRITEQDF.EXE to read the query into SMS

In the Sms\Vtrun40 directory:

Copyvt.bat | Copies all Visual Test 4.0a runtime files to SMS site
X86vt.bat | Copies x86 Visual Test 4.0a runtime files to SMS site
Alphavt.bat | Copies ALPHA Visual Test 4.0a runtime files to SMS site
Copyvt.pdf | Package Definition File

In the Sms\Vtrun40\X86 and Sms\Vtrun40\Alpha directories:

Mtrun.exe | Visual Test 4.0a runtime file
Mstest40.dll | Visual Test 4.0a runtime file
Msvcrt40.dll | Visual Test 4.0a runtime file
Loger2nt.dll | Visual Test 4.0a runtime file

In the Sms\Ntinvcol\I386 directory:

Instpoll.exe

Application for installing POLLINV on logon servers

In the Sms\Pcm_Svc\I386 and Sms\Pcm_Svc\Alpha directories (new):

See the Systems Management Server Resource Guide Supplement, Chapter 2 for instructions on how to install and use the files in this directory.

Pcmsvc32.exe | Service run on NT clients, which allows PCM to be run as a Service
Pcmwin32.exe | Replacement PCM client application used when running PCM as a Service on NT clients

In the Sms\Netboot directory:

Apadmin.mdb | Stores current settings (note that you need to have read/write access)
Apsnet.dll | Netboot floppy admin extension DLL
Mfc42.dll | C run-time DLL (must be in Win95\System or Winnt\System32)
Msvcrt.dll |
Netboot.exe | Netboot floppy administrator main executable
Netboot.hlp | Help file for Netboot floppy

In the Sms\Netboot\Floppy:

Note All of these files are required to build a floppy (must have read/write access).

In the .\Drivers directory:

Cendis.exe

Dc21040.dos

Defea.dos

Depca.dos

Depca.scr

Dhcp.prm

E100b.dos

Elnk3.dos

Elnkii.dos

Elpc3.dos

Epro.dos

Exp16.dos

Lmhosts

Ndis595.dos

Ne2000.dos

Nemm.dos

Netflx.dos

Netflx.scr

Networks

Nwlink.exe

Pcntnd.dos

Pcntnd.scr

Pe2ndis.exe

Pe3ndis.exe

Services

Smc9000.dos

Tcpdrv.dos

Tcptsr.exe

Tcputils.ini

Tinyrfc.exe

Ubnei.dos

Xpsndis.exe

In the .\Preui directory:

Auto2.bat

Chkpriv.exe

Detect.exe

Devices.ini

Mode.com

Mouse.com

Ndishlp.sys

Net.exe

Net.ini

Net.msg

Netcard.scr

Nstrt.bat

Prelang.ini

Protman.dos

Protman.exe

Protocol.gen

Protocol.scr

Scripter.exe

System.gen

System.scr

Validom.ini

Vinfo.exe

Wfwsys.cfg

In the .\Root directory:

Autoexec.bat

Config.sys

Setramd.bat

In the .\Root\bin directory:

Ed.com

Extract.exe

Findramd.exe

Qdel.com

Reboot.com

In the .\Root\dos directory:

Ansi.sys

Emm386.exe

Fdisk.cab

Himem.sys

Ramdrive.sys

Smartdrv.exe

In the .\Root\net directory:

Ifshlp.sys

Net.cab

Preui.cab

In the .\System directory:

Boot.sec

Command.com

Io.sys

Msdos.sys

In the Sms\Sitesu directory:

Sites.pdf | Package definition file
Upgrade.pcd | Compiled Visual Test file
Bvtdlg.pcd | Compiled Visual Test file
Address.ini | Contains site addresses
Su.ini | Contains site setup information
Updproxy.bat | Copies proxy files for PGC installations
Cpy2root.pdf | Package definition file

In the Sms\Upg2site\I386 and Sms\Upg2site\Alpha directories:

See the file Upg2site.doc in the Sms\Docs directory for instructions on how to use these files.

Setup.exe | SMS setup for controlled secondary site upgrade
Upg2site.exe | Utility for manually upgrading a secondary site
setup2.cmd | Wrapper to setup.exe to avoid typing errors

In the Sms\W95dep directory:

Readme.txt

Description of the Systems Management Server Deployment Guide for Microsoft® Windows® 95 and Microsoft Office for Windows 95

In the Sms\W95dep\Doc directory:

Sms__toc.doc | Table of contents for the Systems Management Server Deployment Guide for Microsoft® Windows® 95 and Microsoft Office for Windows 95
Sms_intr.doc | Introduction
Sms_pt_1.doc | Part 1
Sms_pt_2.doc | Part 2
Sms_pt_3.doc | Part 3
Sms_pt_4.doc | Part 4
Sms_pt_5.doc | Part 5

In the Sms\W95dep\Pdf&Inf directory:

Winofc95.inf | Combined Windows 95 and Office for Windows 95 setup.
Win95tcp.inf | Auto-install of Windows 95 using Microsoft TCP/IP and DHCP protocol Settings.
Win95nw.inf | Auto-install of Windows 95 using Microsoft client for Netware networks.
Winofc95.pdf | PDF for combined Windows 95 and Office for Windows 95 setup.
Off95std.pdf | PDF for auto-install of Office for Windows 95.
Scandisk.pdf | PDF for scandisk used to check disks prior to upgrades.

In the Sms\W95dep\Plus directory:

Note These are the files required for deploying the Windows 95 Plus! Pack.

Batch.doc

Plus!.pdf

Plus.dll

Plus.inf

Plus.stf

Proxy.txt

Setup.lst


5.3 Microsoft Exchange Server File List

See section 6.2, below, for information on the Exchange Server files in this release.


5.4 Microsoft SNA Server File List

In the Bork\SNA directory:

BINDERY.EXE | Bindery application file
BITFLIP.EXE | BitFlip application file
CLEANUP.EXE | SNA Server removal application (command-line tool)
CLEANUP.INI | Required for running Cleanup.exe
DISPLAY.EXE | SNA Server Display application (command-line tool)
DRWATSON.EXE | 16-bit event log application
GETSENSE.EXE | APPC error code display application (command-line tool)
HEAPWALK.EXE | Application to display 16-bit Windows information
SENSDATA.DAT | The GETSENSE data file
SNATALK.EXE | Tool to list SNA Server computers and their Banyan VINES StreetTalk addresses.
TOOLS.CNT | Microsoft SNA Server Help Contents
TOOLS.HLP | Microsoft SNA Server Help
WINDEF.HLP | Microsoft Help window definition

APPCTest File List

The APPCTest program is in the \Program Files directory on the computer on which you installed it. The files are:

snatest.exe | Pre-built version of APPCTest program
st4unst.* | Uninstall files

The source code files for APPCTest are located on the BackOffice Resource Kit CD-ROM in the \sna\Appctest\src directory. The files are:

APPC.bas | WinAPPC.H symbolic constants and data structures (APPC Verbs)
APPCtest.vbp | VB 4.0 project file for APPCTest project
CSV.bas | WinCSV.H symbolic constants and data structures (Common Service Verbs)
FrmABOUT.* | ABOUT box form
FrmMDI.* | MDI parent window form
FrmPassword.* | Password Prompt form
msg32.oc* | MSG32 OLE Custom Control module
msstart.bmp | The Start button in bitmap
oneconv.bas | Static data area for APPC conversation
Pointer32.bas | Utility functions for accessing Win32 pointer datatypes from VB
Sna.* | SEND child window form
snadll.dll | ASCII / EBCDIC conversion routines (avoiding use of CSV CONVERT verb)
snarecv.* | RECEIVE child window form

The setup files for APPCTest are located on the BackOffice Resource Kit CD-ROM in the \sna\Appctest\setup directory. To install the application and all its required custom controls, run SETUP.EXE from this directory.

In the SNA\ActiveLU directory

ACTIVELU.DLL | DLL required for ActiveLU.exe
ActiveLuClient.exe | ActiveLU client application
CRREMOBJ.DLL | Required DLL for ActiveLU.exe
RemoteLUPool.exe | Application to determines remote LUs
RLPCLNT.EXE |
RLPEXPL.EXE | Remote LU Pool Explorer displays the status of LUs in pools


5.5 Microsoft SQL Server File List

In the Sql\Arcadia directory:

Ctl3d32.dll

Dao3032.dll

Default.cfg

Dwsetup.exe

Msjint32.dll

Msjt3032.dll

Msjter32.dll

Msrd2x32.dll

Msvcirt.dll

Msvcrt.dll

Msvcrt20.dll

Msvcrt40.dll

Mswng300.dll

Odbcji32.dll

Odbctl32.dll

Olepro32.dll

Sqlole65.tlb

Threed32.ocx

Vb40032.dll

Vbajet32.dll

Vbar2232.dll

In the Sql\Arcadia\Wwwfiles directory:

cpyright.htm

DataAnalysisSummary.htm

datadollar.htm

default.htm

DWSummary.htm

Footer.txt

frbanner.htm

Global.ASA

GlobalVisual BasicFunc.txt

lthous5.avi

Lthous6.avi

PressRelease1.htm

PressRelease2.htm

SystemLogin.htm

WHLocTop.htm

WHOrderYes.htm

In the Sql\Arcadia\Wwwfiles\Audio directory:

ocean.wav

In the Sql\Arcadia\Wwwfiles\Controls directory:

Ieanbtn.ocx

Ielabel.ocx

Iemenu.ocx

In the Sql\Arcadia\Wwwfiles\Dbdats directory:

Abdwbkup.dat

Aboebkup.dat

In the Sql\Arcadia\Wwwfiles\Dw_ppt directory:

Axplayer.exe

Dw_ppx.ppz

Various .htm, .gif, and .jpg files.

In the Sql\Arcadia\Wwwfiles\Images directory:

Various .gif and .jpg files.

In the Sql\Arcadia\Wwwfiles\Scripts directory:

AboutThisDemo.asp

code.asp

frconten.asp

Frmain.asp

ImplementSQLMailFeature.asp

LoadSoftware.asp

LoadTransform.asp

LoadTransSim.asp

SystemSetup.asp

SystemSetup1.asp

SystemSetupLogon.asp

SystemSetupSetParameter.asp

WHEmpDrill1.asp

WHEmpDrill2.asp

WHLocDrill1.asp

WHLocDrill1A.asp

WHLocDrill1B.asp

WHLocDrill1C.asp

WHLocDrill1D.asp

WHLocDrill2.asp

WHMfgDrill1.asp

WHMfgDrill2.asp

WHMmbrDrill1.asp

WHMmbrDrill2.asp

WHOrderDrill1.asp

WHOrderNo.asp

WHOrderSendMail.asp

WHOrderTop.asp

WHProdDrill1.asp

WHProdDrill2.asp

WHProdDrill3.asp

WHProdDrill3C.asp

WHProdDrill3S.asp

WHTimeDrill1.asp

WHTimeDrill2.asp

WHTimeDrill3.asp

WHTimeDrill4.asp

WHTimeDrill5.asp

In the Sql\Arcadia\Wwwfiles\Setup directory:

ASPConnPooling.reg

RunReg.bat

SetupDWUsers.sql

SetupOEUsers.sql

SetupUsers.BAT

In the Sql\Arcadia\Wwwfiles\Setup\Axplayer directory:

Axplayer.exe

In the Sql\Arcadia\Wwwfiles\Setup\Transform directory:

Arcadi~1.ex_

Comctl32.oc_

Comdlg32.oc_

Ctl3d32.dl_

Mfc40.dl_

Msrdc32.oc_

Msrdo32.dl_

Msvcrt20.dl_

Msvcrt40.dl_

Olepro32.dl_

Setup.exe

Setup.lst

Setup132.ex_

St4unst.ex_

Stkit432.dl_

Vb40032.dl_

Ven2232.ol_

In the Sql\Arcadia\Wwwfiles\Setup\Transim directory:

Arcadi~1.ex_

Comctl32.oc_

Comdlg32.oc_

Ctl3d32.dl_

Mfc40.dl_

Msrdc32.oc_

Msrdo32.dl_

Msvcrt20.dl_

Msvcrt40.dl_

Olepro32.dl_

Setup.exe

Setup.lst

Setup132.ex_

St4unst.ex_

Stkit432.dl_

Vb40032.dl_

Ven2232.ol_

In the Sql\Arcadia\Wwwfiles\Works directory:

Various .htm and .gif files.

In the Sql\Arcadia\Wwwfiles\Works\Images directory:

Various .gif files.

In the Sql\Dbcheck directory:

Dbchkcrs.sql | Generates a secondary ISQL script for SQL Server version 6.x and later.
Dbchktbl.sql | Generates a secondary ISQL script for SQL Server version 4.2x.

In the Sql\Docs directory:

Sql.hlp

Help for the Microsoft SQL Server tools on the CD ROM.

In the Sql\Examples directory:

Adduser.sql | Example SQL script.
Deadlock.sql | Creates tables and stored procedures for deadlock demonstration.
Dmosamp.frm | Example Visual Basic form.
Dmosamp.vbp | Example Visual Basic project.
Firstsql.cpp | Example C++ code.
Sqldump.sql | Example SQL script.

In the Sql\Filltabl directory:

Filltabl.exe

Fill Table tool.

In the Sql\Loadsim directory:

Sqlls.exe | SQL Load Simulator tool.
Sqlls.hlp | Help for the SQL Load Simulator tool on the CD-ROM.

In the Sql\Sprocs directory:

Spdropfk.sql | Installs the sp_drop_fkeys stored procedure.
Sphsetop.sql | Installs the sp_help_set_options stored procedure.
Sphstxt.sql | Installs the sp_help_sourcetext stored procedure.

In the Sql\Sqlcomp directory:

Setup.exe | Setup for SQL Comparison tool.
Setup.ini |
Setup.ins |
Setup.iss |
Setup.pkg |
_INST32I.ex_ |
_ISDEL.exe |
_SETUP.1 |
_SETUP.2 |
_SETUP.3 |
_SETUP.dll |
_SETUP.lib |

In the Sql\Sqlhdtst directory:

Sqlhdtst.exe

Sqlhdtst tool.

In the Sql\Sqltrend directory:

Appusage.bmp | Bitmap of application_sum function pie chart.
Checkfor_10minute_sum.sql | Checks for 10minute_sum table.
Checkfor_application_sum.sql | Checks for application_sum table.
Checkfor_audit.sql | Checks for audit table.
Checkfor_cmd_stats.sql | Checks for cmd_stats table.
Checkfor_day_sum.sql | Checks for day_sum table.
Checkfor_hour_sum.sql | Checks for hour_sum table.
Checkfor_minute_sum.sql | Checks for minute_sum table.
Checkfor_perf.sql | Checks for perf database.
Checkfor_sqltrace.sql | Checks for sqltrace table.
Checkfor_user_sum.sql | Checks for user_sum table.
Comusage.bmp | Bitmap of cmd_stats function pie chart.
Createperf.sql | Creates perf database.
Create_10minute_sum.sql | Creates 10minute_sum table.
Create_application_sum.sql | Creates application_sum table.
Create_audit.sql | Creates audit table.
Create_cmd_stats.sql | Creates cmd_stats table.
Create_day_sum.sql | Creates day_sum table.
Create_hour_sum.sql | Creates hour_sum table.
Create_minute_sum.sql | Creates minute_sum table.
Create_sqltrace.sql | Creates sqltrace table.
Create_user_sum.sql | Creates user_sum table.
Del_sp_import.sql | Deletes sp_import stored procedure.
Del_sp_startsqltrace.sql | Deletes sp_startsqltrace stored procedure.
Droptemps.sql | Drops temp table.
Execbat2.exe | This is like ISQL but returns error codes.
Import.cmd | Command file for performing import of flat files to SQL tables.
Mainscr.bmp | Main screen bitmap.
Make_startup.sql | Not used.
Setup.cmd | Sets up SQL Trend Analyzer.
Sp_import.sql | Stored procedure.
Sp_startsqltrace.sql | Stored procedure.
SQLTrend Reports 97.xls | Excel-based reporting front end for SQLTrend Analyzer.
Startsqltrend.cmd | Starts SQL Trend Analyzer.
Stopsqltrend.cmd | Stops SQL Trend Analyzer.
Sumhour.bmp | Bitmap of hour_sum function Excel graph.
Summin.bmp | Bitmap of minute_sum function Excel graph.
Sumten.bmp | Bitmap of 10minute_sum function Excel graph.
Usrusage.bmp | Bitmap of user_sum function Excel pie chart.

In the Sql\Swp directory:

Remove.sql | Removes the tables from a SQL Server database.
Sqlwpub.exe | Single file installation of SQL Workbook Publisher, Publisher.
Sqlwpub.sql | Installs tables and stored procedures in a SQL Server database.
Sqlwview.exe | Single file installation of SQL Workbook Publisher, Viewer.
Readme.txt | Readme file with installation instructions.

In the Sql\Swp\Publish directory:

Comctl32.oc_ | Visual Basic 4 Runtime.
Ctl3d32.dl_ | Visual Basic 4 Runtime.
Mfc40.dl_ | Visual Basic 4 Runtime.
Msrdo32.dl_ | Visual Basic 4 Runtime.
Msvcrt20.dl_ | Visual Basic 4 Runtime.
Msvcrt40.dl_ | Visual Basic 4 Runtime.
Odbc32.dl_ | ODBC.
Olepro32.dl_ | Visual Basic 4 Runtime.
Setup.exe | Setup for Publisher installation of SQL Workbook Publisher.
Setup.lst | Setup program.
Setup132.ex_ | Setup program.
Sqlwpub.cn_ | Help file.
Sqlwpub.dl_ | IE3 Helper DLL for Sqlwpub.
Sqlwpub.ex_ | SQL Workbook Publisher.
Sqlwpub.gi_ | Help file.
Sqlwpub.hl_ | Help file.
Sqlwpub.xl_ | SQL Workbook Publisher.
St4unst.ex_ | Uninstaller.
Stkit432.dl_ | Setup program.
Tabctl32.oc_ | Visual Basic 4 Runtime.
Threed32.oc_ | Visual Basic 4 Runtime.
Vb40032.dl_ | Visual Basic 4 Runtime.
Ven2232.ol_ | Visual Basic 4 Runtime.

In the Sql\Swp\Viewer directory:

Comctl32.oc_ | Visual Basic 4 Runtime.
Ctl3d32.dl_ | Visual Basic 4 Runtime.
Mfc40.dl_ | Visual Basic 4 Runtime.
Msrdo32.dl_ | Visual Basic 4 Runtime.
Msvcrt20.dl_ | Visual Basic 4 Runtime.
Msvcrt40.dl_ | Visual Basic 4 Runtime.
Odbc32.dl_ | ODBC.
Olepro32.dl_ | Visual Basic 4 Runtime.
Setup.exe | Setup for Viewer installation of SQL Workbook Publisher.
Setup.lst | Setup program.
Setup132.ex_ | Setup program.
Sqlwpub.cn_ | Help file.
Sqlwpub.dl_ | IE3 Helper DLL for Sqlwpub.
Sqlwpub.ex_ | SQL Workbook Publisher.
Sqlwpub.gi_ | Help file.
Sqlwpub.hl_ | Help file.
Sqlwpub.xl_ | SQL Workbook Publisher.
St4unst.ex_ | Uninstaller.
Stkit432.dl_ | Setup program.
Tabctl32.oc_ | Visual Basic 4 Runtime.
Threed32.oc_ | Visual Basic 4 Runtime.
Vb40032.dl_ | Visual Basic 4 Runtime.
Ven2232.ol_ | Visual Basic 4 Runtime.

In the Sql\Swp\Intranet\Scripts directory:

Database.htx | Format file for Sqlwpub Internet connection.
Database.idc | Query file for Sqlwpub Internet connection.
Folders.htx | Format file for Sqlwpub Internet connection.
Folders.idc | Query file for Sqlwpub Internet connection.

In the Sql\Swp\Intranet\Wwwroot directory:

Various .gif and .htm files.

In the Sql\Swp\Intranet\Wwwroot\Help directory:

Various .gif and .htm files.


6.0 Directory Structure of the Microsoft BackOffice Resource Kit: Part Two CD-ROM

The following is the directory structure of the Microsoft BackOffice Resource Kit: Part Two CD-ROM. The subdirectory names on the CD-ROM correspond to the categories you can choose from during the Setup process. When installed, the files for the tools that you selected during Setup will be installed on your hard disk under the directory you specified during installation or one of its subdirectories.


6.1 Under Registry Key:

The following directories are under \Sms on the Microsoft BackOffice Resource Kit: Part Two CD-ROM.

Directory \Subdirectory | Description
\Bins |
\Alpha | Alpha 32-bit server applications
\Nt351 | Alpha 32-bit server applications specific to NT 3.51
\Nt40 | Alpha 32-bit server applications specific to NT 4.0
\I386 | Intel 32-bit server applications
\Nt351 | Intel 32-bit server applications specific to NT 3.51
\Nt40 | Intel 32-bit server applications specific to NT 4.0
\Clients |
\Alpha | Alpha 32-bit client applications
\I386 | Intel 32-bit client applications
\Win16 | 16-bit client applications
\Docs | Help files and other documents
\Netboot | Netboot floppy tool
\Floppy | Directory structure required for building a Netboot floppy
\Drivers |
\Preui |
\Root |
\Bin |
\Dos |
\Net |
\System |
\Ntinvcol |
\I386 | Windows NT Inventory File Collection applications for Intel
\Pcm_svc |
\I386 | Files for running Program Command Manager as a Service on Intel NT clients
\Alpha | Files for running Program Command Manager as a Service on Alpha NT clients
\Queries | SQL Query Definition Files (QDF) for Office97 installation
\Sitesu | Files for remote site setup/upgrade files
\Upg2site |
\I386 | Executables for the controlled upgrade of secondary sites for Intel servers
\Alpha | Executables for the controlled upgrade of secondary sites for Alpha servers
\Vtrun40 | Files for remote install of Visual Test 4.0 files
\Alpha | Visual Test 4.0 files for Alpha
\X86 | Visual Test 4.0 files for Intel
\W95dep | Systems Management Server Deployment Guide for Microsoft® Windows® 95 and Microsoft Office for Windows 95
\Doc | Document files for the Systems Management Server Deployment Guide for Microsoft® Windows® 95 and Microsoft Office for Windows 95
\Pdf&inf | .pdf and .inf files for deploying Windows 95 and Office 95
\Plus | Files for auto-installing the Microsoft Plus! pack


6.2 Microsoft Exchange Server Directory Structure

The following directories are under \Exchange on the Microsoft BackOffice Resource Kit: Part Two CD-ROM.

Directory \Subdirectory | Description
\Common | Platform independent Exchange tools
\MSMail | Microsoft Mail Resource Kit tools
\NLS | Natural Language Support Configuration Tool
\Docs | Online documents for Microsoft Exchange Server
\win95 | Exchange tools for Windows 95
\admin | Exchange Administrative tools for Windows 95
\Aspirin | Aspirin Asn-1 Decoder Tool
\Chgroute | Microsoft Mail Route Change Tool
\Cleanswp | Cleansweep Tool
\Crystal | Crystal Reports for Exchange
\Dropper | Buddy Dropper Tool
\EventLog | Event Log Tools
\Eximwiz2 | Microsoft Exchange Address Export/Import to Microsoft Mail Tool
\Mailstrm | Mailstorm Tool
\MAPIsend | Command Line Mail Sender
\MgmtList | Management Chain List Tool
\OnDL | Distribution List Membership Search Tool
\Pkicker | Proxy Modification Tool
\Profgen | Profile Generator Tool
\client | Exchange Client tools for Windows 95
\Autofill | Autofill Tool
\autosig | AutoSig Tool
\GloblSnd | Global Send Options Tool
\Inetxidm | Internet Idioms Tool
\SchedABA | Schedule+ Address Book Assistant
\SMH | Simple Mail Handler
\SrvSpace | Server Space Client Extension
\Switchfm | SwitchForms Tool for Microsoft Outlook
\Tripane | Preview Pane Extension
\developer | Exchange Developer tools for Windows 95
\EFDHandc | EFD Hand Code Tool
\MAPIndl | MAPI Lotus Notes Document Link Tool
\RPCcount | RPC Counter
\migrate | Exchange Migration tools for Windows 95
\Proxy | Microsoft Mail Proxy to Microsoft Exchange Proxy Conversion Tool
\MODELING | Exchange Modelling tool for Windows 95
\Domplan | NT Domain Planner tool
\Maps | Bitmaps of states and countries used by the Windows NT Domain Planner
PFtools | Exchange Public Folder tools for Windows 95
\Pftree | Public Folder Tree Information Tool
\Replver | Public Folder Replication Verify Tool
\Security | Exchange Security tools for Windows 95
\Sectool | Bulk Advanced Security Tool
\SELFCERT | Self-Certification Form for Temporary Export of Encryption Software
\winnt | 32-bit server applications for Windows NT
\alpha | Alpha 32-bit server applications for Windows NT
\admin | Exchange Administrative tools for Windows NT on the Alpha platform
\Aspirin | Aspirin Asn-1 Decoder Tool
\Cleanswp | Cleansweep Tool
\Crystal | Crystal Reports for Exchange
\Dropper | Buddy Dropper Tool
\DupProxy | Duplicate Proxy Search Tool
\Eventlog | Event Log Tools
\Mailstrm | Mailstorm Tool
\MAPIsend | Command Line Mail Sender
\OnDL | Distribution List Membership Search Tool
\Phone | Phone Book Search Tool
\Pkicker | Proxy Modification Tool
\Profgen | Profile Generator Tool
\Sentinel | Sentinel Tool
\client | Exchange Client tools for Windows NT on the Alpha processor
\Autofill | Autofill Tool
\GloblSnd | Global Send Options Tool
\Inetxidm | Internet Idioms Tool
\SMH | Simple Mail Handler
\SrvSpace | Server Space Client Extension
\Migrate | Exchange Migration tools for Windows NT on the Alpha processor
\MigSMTP | Microsoft Mail SMTP Gateway Proxy Migration Tool
\Proxy | Microsoft Mail to Microsoft Exchange Proxy Conversion Tool
\PFtools | Exchange Public Folder tools for Windows NT on the Alpha processor
\Pftree | Public Folder Tree Information Tool
\Security | Exchange Security tools for Windows NT on the Alpha processor
\sectool | Bulk Advanced Security Tool
\SELFCERT | Self-Certification Form for Temporary Export of Encryption Software
\i386 | Intel 32-bit server applications for Windows NT
\admin | Exchange Administration tools for Windows NT on the i386 processor
\AdminAgt | Administrative Mailbox Agent
\Aspirin | Aspirin Asn-1 Decoder Tool
\Chgroute | Microsoft Mail Route Change Tool
\Cleanswp | Cleansweep Tool
\Crystal | Crystal Reports for Exchange
\Dropper | Buddy Dropper Tool
\DupProxy | Duplicate Proxy Search Tool
\EVENTLOG | Event Log Tools
\Eximwiz2 | Microsoft Exchange Address Export/Import to Microsoft Mail Tool
\IMCext | Internet Mail Connector Sample Extension DLL
\Mailstrm | Mailstorm Tool
\MAPIsend | Command Line Mail Sender
\MBClean | Mailbox Cleanup Agent
\MBMigrat | Mailbox Migraton Tool
\MgmtList | Managemment Chain List Tool
\OnDL | Distribution List Membership Search Tool
\Phone | Phone Book Search Tool
\Pkicker | Proxy Modification Tool
\Profgen | Profile Generator Tool
\Sentinel | Sentinel Tool
\client | Exchange Client tools for Windows NT on the i386 processor
\Autofill | Autofill Tool
\GloblSnd | Global Send Options Tool
\Inetxidm | Internet Idioms Tool
\SchedABA | Schedule+ Address Book Assistant
\SMH | Simple Mail Handler
\SrvSpace | Server Space Client Extension
\Switchfm | SwitchForms Tool for Microsoft Outlook
\Tripane | Preview Pane Extension
\developer | Exchange Developer tools for Windows NT on the i386 processor
\EFDHandc | EFD Hand Code Agent
\MAPIndl |
\RPCcount | RPC Counter
\Migrate | Exchange Migration tools for Windows NT on the i386 processor
\Header | Import Header tool
\MigSMTP | Microsoft Mail SMTP Gateway Proxy Migration
\Proxy | Microsoft Mail to Microsoft Exchange Proxy Conversion Tool
\MODELING | Exchange Modelling tool for Windows NT on the i386 processor
\Domplan | NT Domain Planner tool
\Maps | Bitmaps of states and countries used by the Windows NT Domain Planner
\PFtools | Exchange Public Folder tools for Windows NT on the i386 processor
\PFAdmin | Public Folder Administraton Tool
\Pftree | Public Folder Tree Information Tool
\Replver | Public Folder Replication Verify Tool
\Security | Exchange Security tools for Windows NT on the i386 processor
\Sectool | Bulk Advanced Security Tool
\Selfcert | Self-Certification Form for Temporary Export of Encryption Software
\ppc | Power PC 32-bit server applications for Windows NT
\admin | Exchange Administration tools for Windows NT on the PowerPC processor
\Aspirin | Aspirin Asn-1 Decoder Tool
\Dropper | Buddy Dropper Tool
\Mailstrm | Mailstorm Tool
\Sentinel | Sentinel Tool
\client | Exchange Client tools for Windows NT on the PowerPC processor
\GloblSnd | Global Send Options Tool
\SMH | Simple Mail Handler
\PFtools | Exchange Public Folder tools for Windows NT on the PowerPC processor
\Pftree | Public Folder Tree Information Tool
\samples | Sample code for Exchange Resource Kit tools
\IMCext | Internet Mail Connector Sample Extension DLL
\OnDL | Distribution List Membership Search Tool
\UnixSE | Unix Mail Source Extractor Tool


6.3 Microsoft SNA Server Directory Structure

The following directories are under \Sna on the Microsoft BackOffice Resource Kit: Part Two CD-ROM.

Directory Subdirectory | Description
\Appctest |
\setup | Setup files for APPCTest
\src | Source files for APPCTest
\Cleanup |
\Release | Cleanup files for each supported platform
\Sna30 |
\Clients | Cleanup files for Windows 95 and Windows NT
\Server |
\Docs | Help files for SNA Server tools
\Tools |
\Bindery.exe | Application program for Bindery
\Bitflip.exe | Application program for Bitflip
\Cleanup.exe | I386 application program for Cleanup
\Cleanup.ini | Configuration settings for Cleanup
\Display.exe | Application program for Display
\DrWatson.exe | Application program for 16-bit DrWatson
\GETSENSE.exe | Application program for GETSENSE
\Heapwalk.exe | Application program for Heapwalk
\Sensdata.dat | DAT file for GETSENSE
\snatalk.exe | Application program for SnaTalk


6.4 Microsoft SQL Server Directory Structure

Directory | Description
\Dbcheck | A utility that checks the integrity of databases
\Docs | A Help file for the SQL Server utilities
\Examples | Example files for the SQL Server tools and utilities
\Filltabl | A utility that generates a large amount of data for a table
\Loadsim | An application that simulates a large number of user connections to SQL Server
\Sprocs | Stored procedures that drop foreign key constraints for a referenced table, report the current state of the SET options for a connection, and address formatting problems encountered with sp_helptext
\Sqlcomp | A tool that performs object comparisons across a subset of SQL Server object types
\Sqlhdtst | A utility that performs a high-intensity, multithreaded file system stress test
\Sqltrend | A tool that collects, stores, and analyzes performance information obtained from SQL Trace
\Swp | A Microsoft Excel add-in that allows users to analyze data stored in SQL Server databases


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.