Legal Information

Microsoft BackOffice Programmer's Reference

Information in this document is subject to change without notice. This document is provided for informational purposes only and Microsoft Corporation makes no warranties, either express or implied, in this document. The entire risk of the use or the results of the use of this document remains with the user. 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. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft.

© 1996–1998 Microsoft Corporation. All rights reserved.

BackOffice, Microsoft, Microsoft Press, MS, MS-DOS, Visual Basic, Visual C++, Windows, Win32, Win32s and Windows NT are either registered trademarks or trademarks of Microsoft Corporation in the U.S. and/or other countries.

Intel is a registered trademark of Intel Corporation.

Macintosh is a registered trademark of Apple Computer, Inc. used under license.

Other product and company names herein may be the trademarks of their respective owners.


Document Conventions

This reference uses the following typographical conventions:

  • UPPERCASE text represents statement and clause names, structure names, file names, and paths.
  • Bold text indicates an interface, method, function, structure, or other keyword. Within discussions of syntax, bold type indicates that the text must be entered exactly as shown.
  • Italic text indicates a new or unfamiliar term, or a reference to a source outside of the Microsoft BackOffice Programmer’s Reference.


Developing Applications in the Microsoft BackOffice Environment

Microsoft® BackOffice®, built on Microsoft® Windows NT® Server, is an integrated platform for building business solutions for your company's network, intranet, and the Internet. BackOffice offers developers a consistent development environment for the desktop, the server, and the Internet, allowing you to leverage what you already know to quickly build powerful solutions.

This section presents relevant design and programming issues to consider during the development of a server or client application that will interact with the BackOffice components. Additionally, this section introduces many programming concepts and techniques that are fundamental to developing any application that requires optimum performance and maximum functionality.


BackOffice Server Components

The Microsoft® BackOffice® family of server software includes the following BackOffice Server components:

  • Microsoft Windows NT Server—a multipurpose network operating system that delivers broad application server and networking capabilities within a secure environment.
  • Microsoft Internet Information Server—a complete FTP, Gopher, and World Wide Web information service specifically designed to run on Microsoft Windows NT and within the BackOffice environment.
  • Microsoft Index Server—works with Windows NT Server version 4.0 and Internet Information Server version 2.0 to provide an organization access to all of the documents stored on its intranet or Internet site.
  • Microsoft Proxy Server—the easy and secure way to bring Internet access to every desktop in an organization.
  • Microsoft Exchange Server—a complete messaging and workgroup software solution.
  • Microsoft SQL Server—a high-end database platform designed to be the center of a complete information management system.
  • Microsoft Systems Management Server (SMS)—the most comprehensive solution for managing networked personal computers.
  • Microsoft SNA Server—the easiest system to connect personal computers to IBM mainframes and AS/400 mid-range systems.

The components of BackOffice Server were designed to work together and, consequently, share a solidly defined and supported, truly open architecture: Microsoft's widely-endorsed Windows Open Services Architecture (WOSA).


Windows NT Server

Microsoft® Windows NT® Server provides the connectivity, reliability, base services, and administrative tools necessary to deliver critical business information across a distributed network of computers. Its scale ranges from the small network to the enterprise, providing basic file and print services while also supporting mission-critical databases, electronic messaging, host connectivity, and distributed systems management. It combines the comprehensive file and print services of Novell NetWare with the application capabilities of UNIX in one multipurpose network operating system.

Improvements in Windows NT Server version 4.0 deliver better performance scalability on multiprocessor systems. New application programming interfaces (APIs) for server application developers and better server performance deliver improved throughput and scalability for server applications. In addition, a set of encryption APIs allow developers to create applications that work securely over non-secure networks, such as the Internet.

As the network foundation for Microsoft BackOffice, Windows NT Server supports numerous turnkey business solutions—from general accounting to manufacturing management and inventory control systems. Windows NT Server has a wide range of protocols and services designed to facilitate the integration of technologies into one easily manageable system. It is engineered to support every popular client operating system, such as Microsoft® MS-DOS®, Microsoft® Windows®, Microsoft® Windows® 95, Windows NT, OS/2, Macintosh, and UNIX.


Internet Information Server

Microsoft Internet Information Server (IIS), which installs and runs as a native Windows NT service, is a powerful platform for a new generation of World Wide Web applications that must interact with other BackOffice components and applications. Microsoft® Internet Information Server offers many features including:

  • Installation integrated into Windows NT Server version 4.0 installation
  • Low system management outlays
  • Scalable and portable design
  • High-performance architecture
  • High reliability
  • Integrated with Windows NT Server 4.0 directory and security services
  • Support for open development solutions
  • Access to BackOffice components
  • Integration with existing databases

Enhancements to Internet Information Server version 2.0 deliver improved programmability using the Internet Server API (ISAPI) and improved database programmability with the Internet Database Connector (IDC) for building Internet applications. In addition, support for both NCSA and CERN style image map files facilitates porting from UNIX systems.

By extending the power of Microsoft BackOffice server products to the Internet, Internet Information Server makes it easy to create powerful solutions that improve communications and deliver high-impact Web sites. IIS leverages Microsoft technology to help you develop a new generation of interactive Web-based applications.


Index Server

Microsoft Index Server is a free, downloadable component of Windows NT Server version 4.0. It includes support for HTML, text, and all Microsoft Office documents, in their original format. Microsoft® Index Server automatically indexes the full text and properties of files on your server, whether it is an intranet, an Internet, or simply a file-and-print server. Index Server allows you to search all of your Web documents, including Microsoft® Word and Microsoft® Excel. Built-in database connectivity enables easy access to your data from any browser.

Index Server offers many features including:

  • Indexing for all documents stored on Windows NT Server 4.0 with Internet Information Server version 2.0
  • Customized query form
  • Automatic maintenance
  • Built-in administrative tools, including performance monitoring
  • Support for multiple languages
  • Extensible architecture

Index Server uses content filters, which are associated with particular document formats, to extract the textual information contained within a formatted file. Content filters comply with the IFilter ActiveX™ programmatic interface published by Microsoft. By writing a content filter, software authors can expose their contents to Index Server for indexing and retrieval by end users.


Proxy Server

Microsoft® Proxy Server tightly integrates with the Windows NT Server platform and Internet Information Server to deliver high-performance Internet access to every desktop in your organization in an easy, secure, and cost-effective way. By sharing a single, secure gateway, Proxy Server eliminates the need to share one dedicated machine for the Internet among multiple users, or to run multiple Internet lines into the organization to provide each desktop with a separate connection.

Proxy Server supports a wide range of applications and protocols, including those with live, streaming audio and video (such as RealAudio and VDOLive), LDAP, IRC, SMTP, and Microsoft SQL Server, providing transparent access from any desktop. Its caching capability stores frequently accessed Internet data on your LAN where users can access it as quickly as other information on the local network. The Auto Dial tool in Proxy Server automatically connects to your Internet service provider (ISP) whenever a user needs information not already stored in the local cache.

Proxy Server offers many features including:

  • Integrates easily with existing networks.
  • Supports both TCP/IP and IPX/SPX protocols.
  • Integrates tightly with the Windows NT Server networking, security, and administrative interface.
  • Supports open standards for broad compatibility.
  • Complies fully with the CERN-proxy standard.
  • Supports the Secure Sockets Layer (SSL) for secure data communication.
  • Includes WinSock Proxy.
  • Delivers high-performance access to the Internet and your intranet.
  • Provides secure, managed access.
  • Integrates tightly with Windows NT Server user authentication.


Exchange Server

Microsoft Exchange Server

Microsoft Exchange Server is a complete messaging and workgroup software system that effortlessly combines e-mail functionality with integrated messaging system services. The Microsoft® Exchange Server component of the Platform SDK provides tools that allow you to enhance Microsoft Exchange Server clients to better meet your corporate needs. You can create unique Microsoft Exchange Server clients that satisfy specific messaging requirements, such as collecting e-mail administration information, presenting unusual views of message contents, or providing enhanced client functionality.

By developing a powerful Microsoft Exchange Client, you can provide a single interface for sending, sharing, accessing, and managing information across multiple platforms and operating systems. Microsoft has provided the Microsoft Exchange Forms Designer to create custom views for displaying information. These forms and views can be combined with public folders to create workgroup software applications. Developers can customize these applications even further with the Microsoft® Visual Basic® programming system or the Microsoft® Visual C++® development system.

Improvements in Microsoft Exchange Server version 5.0 provide the communications and collaboration support required for the Internet and the intranet. Based on both Internet and other open standards, Microsoft Exchange Server 5.0 delivers advanced messaging, collaboration, scheduling, and groupware capabilities. It provides complete open Internet standards support, including POP3, HTTP, HTML, NNTP, LDAP, and SSL. In addition, it includes Active Server support, providing a foundation for building Web-based groupware applications.

The modular client/server architecture in Microsoft Exchange Server provides all the components for distributed enterprise-wide messaging and workgroup software. Special server-based rules can be configured and designed to automatically process incoming messages. Use the Microsoft Exchange Server component of the Platform SDK to integrate your business communications into the BackOffice family of server products and create powerful client/server solutions.


SQL Server

Microsoft® SQL Server is a scalable, high-performance database management system designed specifically for distributed client/server computing. A comprehensive distributed management framework lets you centrally manage all the database servers in your organization. With advanced Windows-based management tools and powerful server-based job scheduling, you can control multiple servers and automate remote operations in a distributed environment. Using the SQL Server component of the Platform SDK, you can access SQL Server features such as data replication, management tools, and an open system architecture to develop effective and unique information solutions.

Many features accessible using the SQL Server component of the Platform SDK are tightly integrated with the Windows NT Server platform. As part of the Microsoft BackOffice family of server software, SQL Server works with other BackOffice components and applications to offer powerful client/server solutions. Highlights of the SQL Server component of the Platform SDK include:

  • A powerful structured query language database server for multiple platforms.
  • Several programming libraries such as DB-Library for C and DB-Library for Visual Basic for interacting with SQL Server.
  • The Microsoft Open Database Connectivity call-level application programming interface (API), which allows clients from different platforms to access multiple SQL Server data sources.
  • The Microsoft Open Data Services server-based API, which allows developers to create effective server applications.
  • Broad Transact-SQL communication support.


Systems Management Server

Microsoft Systems Management Server (SMS) is a centralized management tool that allows you to monitor, administer, and control personal computers and servers throughout your entire corporate network. It has four primary functions:

  • Hardware and software inventory
  • Automated software distribution and installation
  • Remote systems troubleshooting and control
  • Network application management

Using the Microsoft® Systems Management Server component of the Platform SDK you can develop applications that can access hardware and software inventory throughout your network and show you what is located where. You can centrally manage, install, and control applications running on desktops and servers by accessing software distribution and installation information.

By creating and customizing SMS inventory, administrator, and network monitor extensions, you can identify network characteristics and uniquely define user interfaces. You can even remotely control the mouse, screen, or keyboard of any personal computer running the Microsoft MS-DOS or Windows operating system.

Improvements in Microsoft Systems Management Server version 1.2 provide a new ISV application launching facility, support for local settings and localized servers, and a faster, multithreaded dataloader. Windows NT Remote Control fully conforms to the Windows NT Security Model and WinSock is now a supported remote control protocol. Systems Management Server 1.2 also supports SNMP trap forwarding and receiving. In addition, inventory now runs as a service on Windows NT clients.

By taking advantage of the functionality of SMS through the Systems Management Server component of the Platform SDK, you can develop applications that completely manage and administer all aspects of your network.


SNA Server

Microsoft Systems Network Architecture (SNA) Server provides developers with the ability to customize communication between computers running operating systems such as MS-DOS, Windows, Windows 95, Windows NT, Macintosh, OS/2, and UNIX and mid-range computers such as AS/400 and IBM mainframes. Using the Microsoft® SNA Server component of the Platform SDK, you can develop applications that:

  • Employ a variety of data link protocols for communicating between PC client computers and IBM mainframe and AS/400 computers. Suitable data link protocols include:

    Token-ring or Ethernet DLC connections

    Leased or switched telephone line connections

    Public or private packet-switched X.25 connections

    Coax or twisted-pair connections by way of IBM 3x74 cluster controller

    Twinaxial connections to an AS/400

    Hardware connections directly to the mainframe channel

  • Use SNA primary unit (PU) and logical unit (LU) protocols such as PU 2.0, PU 2.1, APPN LEN node, DSPU and TN3270; and LU types 0, 1, 2, 3, and 6.2 for communicating with IBM mainframes and AS/400 computers.
  • Manipulate distributed SNA APIs such as:

    APPC (Advanced Program-to-Program Communications) or CPI-C (Common Programming Interface for Communications) for peer-to-peer applications using LU type 6.2.

    CSV (Common Service Verb) for EBCDIC to ASCII conversion and communication with NetView.

    LUA (Logical Unit Application) for direct access to LU types 0, 1, 2, and 3 data streams.

    EHLLAPI for interfacing with 3270 or 5250 applications.

Improvements in Microsoft SNA Server version 3.0 include a redesigned setup program to provide a common user interface with other Microsoft BackOffice and Office applications. Customers now have the option of using Microsoft Systems Management Server to complete unattended and remote installations of SNA Server and SNA Server clients. SNA Explorer replaces the current SNA Server Administrator tool, and communications between SNA Server 3.0 and its clients can be optionally encrypted on a per-user basis.

SNA Server 3.0 supports up to 5,000 users running up to 15,000 sessions. SNA Print Server provides server-based 3270 and 5250 printer emulation. IBM mainframe security systems are supported and SNA Server uses Windows NT Server's RPC security feature. Automated logon to 5250 and APPC applications is also included. The SNA Server-based Shared Folders Service allows PCs with no SNA client software installed to access AS/400 shared folders files. The TN5250 Service enables any TN5250 emulator to connect to the AS/400 through SNA Server without installing TCP/IP on the AS/400. In addition, the TN3287 Service supports printing with a TN3270 emulator.


Additional Information

More information on the Microsoft® BackOffice™ Server components can be found in the following sources.

Component | Sources for additional information
General information on the BackOffice family of products from Microsoft | http://www.microsoft.com/backoffice Microsoft BackOffice Resource Kit
Microsoft Windows NT Server | http://www.microsoft.com/ntserver Microsoft Windows NT Server 4.0 Resource Kit Microsoft Platform SDK
Microsoft Internet Information Server | http://www.microsoft.com/iis
Microsoft Index Server | http://www.microsoft.com/ntserver/search
Microsoft Proxy Server | http://www.microsoft.com/proxy
Microsoft Exchange Server | http://www.microsoft.com/exchange Microsoft Exchange Server Administrator's Guide
Microsoft SQL Server | http://www.microsoft.com/sql Microsoft SQL Server Administrator's Companion
Microsoft Systems Management Server | http://www.microsoft.com/smsmgmt Microsoft Systems Management Server Administrator's Guide
Microsoft SNA Server | http://www.microsoft.com/sna Microsoft SNA Server Administration Guide

SDK documentation for BackOffice, Win32®, and other technologies can be found in the Microsoft Platform SDK, at http://www.microsoft.com/msdn/sdk.


Licensing the Designed for Microsoft BackOffice Logo

The BackOffice logo program provides a way to demonstrate that a product has been tested and integrated with the BackOffice family. Displaying the Designed for Microsoft BackOffice logo informs customers that your product is designed to give them extra benefits when used with BackOffice.

To carry the Designed for Microsoft BackOffice logo, a product must meet a set of technical criteria as described at http://www.microsoft.com/backoffice/designed.


Planning and Sizing Your Application

As you design your application for the Microsoft® BackOffice® environment, you must consider the BackOffice requirements for an application, and how yours will integrate with the other BackOffice components. If you do not design your application with regard to the physical constraints within BackOffice, the application can adversely affect the performance of other BackOffice components, applications, and ultimately itself. Because of the many possible interactions among components in the BackOffice family, and the complexity of those interactions, you should address several issues during the development phase. Important planning and sizing issues include:

  • The number of users that will simultaneously access your application. The number of users your application can simultaneously support is related to the ability of your application to utilize timing, synchronization, and multithread-safe programming techniques, as well as to properly integrate efficient interprocess communication mechanisms.
  • The amount of physical memory your application will require to operate effectively in the BackOffice environment. For example, memory usage is related to efficient heap and stack memory management within your application.
  • The computer system on which your application will reside, which can directly impact your application's performance.

The following topics present the basic requirements for each of the BackOffice components, and address requirements for interactions among the components.


Microsoft Windows NT Server and Internet Information Server

Both Microsoft® Windows NT® Server version 3.51 or later and Microsoft® Internet Information Server require the following:

  • A 32-bit Intel-based processor (such as Intel 80386/25 or higher), Intel Pentium or Pentium Pro, or supported RISC-based microprocessor such as the MIPS R4000, Digital Alpha AXP, or PowerPC.
  • At a minimum, one hard disk partition with at least 90 MB of available disk space to contain the Windows NT Server system files on Intel-based (80386/25 or higher) systems, and at least 110 MB of available disk space for RISC-based systems.
  • At least 16 MB of system memory (RAM) for Intel-based (80386/25 or higher) or RISC-based systems.

To estimate the required system memory, based on the applications that will be running and files that will be open simultaneously, use the following formula:

required_memory=16+files+applications

In this formula, required_memory is the amount of RAM (in MB) the system is likely to need, files is the total size (in MB) of user-data files that will be open at the same time, and applications is the total size (in MB) of application executable files that will be run from the server at the same time. To compute values for files and applications, you can estimate the average size of the files in each category and multiply by the number of files in each category.

You can use a similar formula to estimate the required hard disk space:

required_disk_space=system_minimum+applications+user_data

In this formula, required_disk_space is the total size (in MB) of required server hard disk space. The minimum amount of disk space required by the operating system itself (including the system swap file) is represented by system_minimum. This amount will be either 250 MB, or the sum of 162 MB and the amount of system memory, whichever is greater. The value applications represents the total installed size of all applications, and user_data is the total amount of disk space allocated to users to store their files, plus 10 percent as a margin for error.

Depending on how you plan to use the computer, you may need a faster microprocessor (or multiple microprocessors) and additional available server hard disk space and system memory to achieve acceptable performance. Because all BackOffice components must reside on Windows NT Server, consider these requirements as the starting point for sizing and planning.


Microsoft Index Server

Microsoft® Index Server requires Windows NT Server version 4.0 or later and Internet Information Server version 2.0 or later, in addition to the following:

  • A 32-bit Intel-based processor (such as Intel 80486/25 or higher), Intel Pentium or Pentium Pro, or supported RISC-based microprocessor such as the MIPS R4x00, Digital Alpha, or PowerPC.
  • Free disk space amounting to 40 percent of the total size of the documents to be indexed, in order to store the document indexes.
  • At least 12 MB of system memory (RAM) for Intel-based systems (16 MB recommended); at least 16 MB for RISC-based systems.
  • VGA or higher resolution monitor.
  • Optionally, one or more network adapter cards, if you want to use Windows NT Server with a network.


Microsoft Proxy Server

Microsoft® Proxy Server requires Windows NT Server version 4.0 or later, Internet Information Server version 2.0 or later, and the Windows NT Server 4.0 Service Pack (provided on the Proxy Server CD-ROM). In addition, Proxy Server requires the following:

  • A 486/33-MHz or higher Intel-based processor, Intel Pentium or Pentium Pro, or supported RISC-based microprocessor compatible with Windows NT Server 4.0.
  • At least 15 MB of available hard disk space for Intel-based systems (20 MB for RISC-based systems).
  • At least 16 MB of system memory (RAM).
  • CD-ROM drive.
  • VGA, Super VGA, or video graphics adapter compatible with Windows NT Server 4.0.


Microsoft Exchange Server

In addition to the development requirements for your application, you should anticipate the run-time system requirements for Microsoft® Exchange Server version 4.0 or later. These requirements are shown in the following table.

Users | Processor | Disk space | RAM
Minimum | Intel 486 or faster; or supported RISC-based microprocessor such as the MIPS R4000 and Digital Alpha AXP; or PowerPC | At least 250 MB of available hard disk space for Microsoft Exchange Server after Windows NT Server has been installed Adequate available disk space for the Windows NT Server pagefile (50 MB plus the amount of physical RAM) | At least 32 MB (48 MB for RISC-based systems)
Recommended | Intel Pentium 90 MHz or faster | Sufficient disk space for your users' e-mail and public folder information Multiple physical drives At least one striped drive set Adequate available hard disk space for the Windows NT Server pagefile (100 MB plus the amount of RAM) | At least 32 MB (48 MB for RISC-based systems)

Note The preceding system requirements are based on the assumption that Microsoft Exchange Server is installed and running on top of Windows NT Server. These requirements incorporate general Windows NT Server requirements but may vary depending on your specific system environment.

For more information about processor or memory requirements for Microsoft Exchange Server, see the Microsoft Exchange Server Concepts and Planning Guide.


Microsoft SQL Server

Microsoft® SQL Server requires a computer with at least 16 MB of RAM. If the server will be configured to participate in data replication as either a distribution or a combined publication/distribution server, it must have at least 32 MB of memory, with at least 16 MB available to SQL Server.

Note The preceding system requirements are only for SQL Server and do not represent requirements for other BackOffice components that are frequently integrated with SQL Server, such as Microsoft Systems Management Server or Internet Information Server.

SQL Server requires a minimum of 60 MB of available hard disk space. Additional memory and disk space may be required, depending on how SQL Server is deployed. The following formula will help you calculate the additional recommended disk space:

additional_space=1.2(dataset)

The size of the additional disk space required is approximately 120 percent of the estimated size of the dataset.

The following formula will help you estimate the additional recommended system memory:

additional_memory=1.08(dataset)+1.04(users)

In this formula, additional_memory is the amount of memory recommended in addition to the minimum of 16 MB. The variable dataset is the estimated size of the dataset, and users is the number of users accessing the server. In other words, the amount of additional memory recommended is 8 percent more than the estimated dataset size, plus 1 MB for every 25 users accessing the server.

Note The preceding system requirements are based on the assumption that Microsoft SQL Server is installed and running on top of Windows NT Server. These requirements incorporate general Windows NT Server requirements but may vary depending on your specific system environment.


Microsoft Systems Management Server

For Microsoft® Systems Management Server (SMS), the site server must be installed on a Windows NT Server domain controller or backup domain controller. The server must have a hard disk formatted for NTFS with at least 100 MB of available space; 500 MB is recommended. The server must also have at least 28 MB of RAM. At least 32 MB of RAM is recommended for production environments.

Microsoft SQL Server must be installed, running, and properly configured before you install SMS. Increase the memory option for the SQL Server configuration to at least 8 MB and increase the open objects option to 5000. If SQL Server is installed on a computer different from the SMS site server, create the site database device and transaction log device on separate devices (for example, SMSDATA and SMSLOG); each should be at least 5 MB.

Any other system requirements your application may have are additional to those criteria required for SMS and SQL Server; you must address these accordingly.

For information about setting up SQL Server to support SMS, see the Microsoft Systems Management Server Administrator's Guide.

Note The preceding system requirements are based on the assumption that Microsoft SMS is installed and running on top of Windows NT Server. They do not include any specific requirements for SQL Server. These requirements incorporate general Windows NT Server requirements but may vary depending on your specific system environment.


Microsoft SNA Server

Microsoft® Systems Network Architecture (SNA) Server requires at least 20 MB of system memory. It also requires a minimum of 7 MB of available hard disk space beyond the requirements for Windows NT Server. Additional memory may be required, depending on the number of users that are simultaneously running SNA Server and their level of usage.

The following table shows the recommended processor and amount of memory for a given number of users and type of usage.

Users, usage | Processor | RAM
Up to 25 users | 486DX/33 | 16 MB
25–500 users, light or intermittent usage | 486DX/66 | 32 MB
500–1500 users, light or intermittent usage | Pentium or RISC | 64–128 MB
1–200 users, heavy usage | 486DX/66 | 32 MB
1–600 users, heavy usage | Pentium or RISC | 64–128 MB
1500–2000 users, up to 10000 sessions | Symmetrical Multi-Processor (SMP) or fast RISC | 64–128 MB

For more information about planning the design for an SNA Server system, see the Microsoft SNA Server Planning Guide.


BackOffice Family

The following table shows the minimum processor type and memory required for the specified number of users to run all Microsoft BackOffice components at a medium level of usage.

Users | Processor | RAM (for Intel) | RAM (for RISC)
1–5 | 486/66 (Recommended: Pentium 90 MHz) | 48 MB | 64 MB
6–30 | Pentium 100 MHz | 64 MB | 80 MB
31–75 | Pentium 133 MHz | 80 MB | 96 MB
76–150 | Pentium 133 MHz | 128 MB | 128+ MB
151–250 | Symmetrical Multi-Processor (SMP) | 128+ MB | 128+ MB


About Security in a BackOffice Environment

Security in the Microsoft® BackOffice® environment is provided by Microsoft® Windows NT® security subsystems and is based on the Windows NT security model. To properly incorporate security concepts into your application, you need to understand the following about the model:

  • The data structures, such as access control lists (ACLs), access control elements (ACEs), security descriptors (SDs), and security identifiers (SIDs).
  • How the operating system itself employs security. You can think of the security API as a set of services that are provided for server applications to protect objects from unauthorized access by clients, similar to the way the event log API provides services that help device drivers and applications log errors and notification events.
  • How BackOffice components use the security data structures and leverage the security APIs provided by the Microsoft® Win32® API to establish and protect objects.

Windows NT allows you to establish a full range of security levels, from no security to C2, the strictest application security level. The following topics describe many important concepts surrounding use of the Windows NT security features in your BackOffice server or client application.


General Windows NT Security Model

The security attributes of each Windows NT object (file, named pipe, registry key, user object, kernel object, private object, and so on) are described by a security descriptor (SD). The security descriptor contains information about the owner of the object and has an access control list (ACL), which specifies users and groups and their access permissions on that object.

Access Control Lists

There are two types of ACLs: discretionary and system. The discretionary ACL (DACL) is controlled by the owner of an object and specifies the access particular users or groups can have to that object. The system ACL (SACL) is controlled by the system administrator, and allows system-level security to be associated with the object. The usage of DACL and SACL APIs is very similar. However, the SACL APIs can only be used by a process with system administrator privileges. Because most security programming does not involve setting the system-level security and it is likely that your BackOffice application will need to set or impersonate the security credentials of users, this discussion will focus on the DACL APIs.

The DACL contains an access control entry (ACE) for each user, global group, or local group that is given access permission (whether allowing or denying access) to the object. When a DACL does not have any ACEs, no access rights have been explicitly granted. Therefore, access to the object is implicitly denied. However, when an object does not have a DACL, no protection is assigned to the object and any access request is granted. A security descriptor for an object is initially set to have a DACL with no ACEs, which means that there is no access for any user. To give access to all users or groups, the DACL for the SD must be explicitly set to NULL.

Security Descriptors

There are two types of security descriptors used in the system: absolute and self-relative. The distinction between these types is very important when programming in a BackOffice environment. An absolute security descriptor contains pointers to the DACL and ACE information. However, the self-relative security descriptor contains information in a contiguous block of memory, so the DACLs and ACEs are positioned at offsets. The security APIs use both absolute and self-relative formats at different times. When your application queries for security descriptor information, the information is always returned by the system in self-relative format. The program can then walk through the offsets to obtain the proper information. However, when you add to or change the security descriptor, it must be in absolute format. When programming a change to the security descriptor, for example, the program must read in security descriptor information in one format, then convert it and write it back in the other format.

A user of a process is assigned an access token, which contains identifiers that represent the user and any group to which the user belongs. This access token is checked against the security descriptor of an object to determine the type of permission the user has with respect to that object. When a client application connects to a server, the server process can impersonate the access token of the client process. This gives the server the ability to check the access permission of the client.

For more information about the Windows NT security model, see the "Windows Base Services" section of the Microsoft Platform SDK, and the Microsoft Windows NT Resource Kit.


Additional Areas of Security

In addition to the general areas of security for Windows NT, you should consider the following areas of security when developing an application in a BackOffice environment.

User Accounts

User accounts are the keys to Windows NT security. You can create as many accounts as needed, and include any user account in as many groups of accounts as are appropriate. You can then permit or limit access to any computer resource to individual accounts or to groups. For your BackOffice application, this means that properly configured user accounts play a significant role in allowing users to access system and application resources. For more information about user accounts, see the Microsoft Windows NT Workstation System Guide or Microsoft Windows NT Server System Guide.

Passwords

Passwords play an integral part in the Windows NT security model and help guarantee that only authorized users can access system and application resources. BackOffice applications should utilize this functionality by following the Unified Logon concepts. For more information about password enforcement options and controls, see the Microsoft Windows NT Workstation System Guide or the Microsoft Windows NT Server System Guide.

File and Directory Protection

A range of file protections can be set on a per-file or per-directory basis, and on a per-user or per-group basis. Your BackOffice application should make extensive use of the features in the Windows NT file system to ensure that file and directory structures are kept secure and are correctly managed. For more information about file and directory protection, see the Microsoft Windows NT Workstation System Guide, Microsoft Windows NT Server System Guide, or the Microsoft Windows NT Resource Kit.

Registry Protection

Because the Windows NT registry is the repository of all system configuration information, it is important to protect it from unauthorized changes. At the same time, individuals and programs that need to access or alter information in the registry must be allowed to do so. As a BackOffice developer you should use the registry to store and manage information relative to your application's initialization needs, such as the system information, user characteristics, or specific application parameters. For more information about the registry and the Registry Editor, see the Windows NT Resource Kit.

Auditing

Windows NT includes built-in auditing capability. This allows you to track which user account was used to attempt a particular kind of access to files or other objects in an application. Auditing can also be used to track logon attempts, shutdowns or restarts of the system, and similar events. For more information about auditing, see the Microsoft Windows NT Workstation System Guide, Microsoft Windows NT Server System Guide, or the Microsoft Windows NT Resource Kit.


Interprocess Communications

For an application to take complete advantage of the features in the Microsoft® BackOffice® environment, you must design it to communicate with other applications as well as with components within BackOffice. Typically, cooperating and communicating applications can be categorized as clients or servers. A client is an application or a process that requests a service from some other process. A server is an application or a process that responds to a client request. Many applications act as both a client and a server, depending on the situation. The process of communication between two or more applications, regardless of their client/server status, is called interprocess communications (IPC).

Before you decide which IPC mechanisms to use in the development of your application, you should determine whether:

  • The application should be able to communicate with other applications running on other computers, or whether it is sufficient for the application to communicate only with other applications on the local computer. Some IPC mechanisms work either on the local computer or over a network; others work only on the local computer.
  • The application should be interoperable, able to communicate with other applications on other computers that may be running under different operating systems (for example, Microsoft® MS-DOS®, Microsoft® Windows® version 3.x, UNIX).
  • The user of your application should have to intervene to choose the other application with which the application communicates, or whether your application can implicitly find its cooperating partners.
  • Performance is critical to the application. All IPC mechanisms include some amount of communications overhead.

Many IPC mechanisms, such as dynamic-link libraries and shared memory, are implemented only on the local system. Other IPC mechanisms, such as distributed COM (DCOM) and remote procedure calls (RPCs), find their primary functionality across networks and between different computer systems. Each IPC mechanism has unique features that singularly describe it, and which you should consider during the development of your application.

Considerations for choosing the appropriate IPC mechanisms are shown in the following diagram.

The following topics describe the specific IPC mechanisms you can incorporate into your application as you develop it for the BackOffice environment.


Distributed COM

The distributed component object model (distributed COM) provides a standard conceptual framework for creating, managing, and accessing object-based components that offer services to other objects and applications. Distributed COM components can be used to expose both data and services to programs created by other vendors, and to write applications in such a way as to take advantage of services provided by others. You can also extend or customize basic distributed COM services to suit the needs of your objects and applications while guaranteeing that they continue to work with other COM objects.

Distributed COM components can exist as parts of an operating system or application, or as stand-alone entities, and, with the introduction of Windows NT 4.0, can be implemented across a network. Distributed COM naturally extends the COM programming model and constructs introduced by OLE 2.0 to work across a network.


Location Transparency

One of the features of distributed COM is location transparency. Client applications are not required to confirm or monitor whether objects are running. Many applications are written without concern as to whether the objects used run within their process, in a different process on the same machine, or in a process on a separate machine. With proper administration, distributed COM allows new applications to take advantage of networking features, but also allows existing applications—thousands of them—to interact with new applications and with each other across networks.


Packaging Transparency

With the distributed COM packaging transparency feature, client applications are not required to confirm or monitor whether objects are packaged as in-process objects (in dynamic-link libraries), or as local or remote objects (in executable files). Distributed COM further allows objects to be packaged as Windows NT services, synchronizing OLE with the rich administrative and system integration capabilities of Windows NT.


Security and Scalability

Distributed COM complements existing OLE features by including the security and scalability features required to build great distributed component software:

  • Free-threaded objects High-performance, scalable object services supporting simultaneous calls can be written for use by remote clients or by clients on the same machine.
  • Launch security The default configuration of distributed COM allows only machine administrators to launch existing classes from a remote client. Launch security is configurable with a machine-wide default and on an overriding per-class basis. Launch security also applies to local launch requests (requests to use classes by users on the same machine), a new feature to local OLE.
  • Access security Distributed COM is similarly configured so that only machine administrators can access existing, published objects from a remote client. Access security is also configurable with a machine-wide default (DefaultAccessPermission), on an overriding per-class basis (AccessPermission) when applicable, and on a per-process basis (CoInitializeSecurity or the default security keys). Access security also applies to local attempts to access classes, a new feature to local OLE.
  • Call-level security Distributed COM offers fine-grained configuration of the call security—how connections and calls are authenticated, authorized, encrypted, and so on—of any connection to an object, as well as the ability of the object to impersonate or act under the authority of the caller.

For more information about distributed COM, see the "COM and ActiveX Object Services" section of the Microsoft Platform SDK.


Windows Sockets

The Windows Sockets specification defines a network programming interface for the Microsoft® Windows® operating system that is based on the socket paradigm popularized in the Berkeley Software Distribution (BSD) from the University of California at Berkeley. Windows sockets provide a single API to which application developers can program and multiple network software vendors can conform. Furthermore, in the context of a particular version of Microsoft Windows, it defines an application binary interface such that an application written to the Windows Sockets API can work with a conformant protocol implementation from any network software vendor.

The basic building block for communication is the socket. A socket is an endpoint of communication to which a name may be bound. Each socket in use has a type and an associated process and exists within communication domains. A communication domain is an abstraction introduced to bundle common properties of threads communicating through sockets. Sockets normally exchange data only with sockets in the same domain (it may be possible to cross domain boundaries, but only if some translation process is performed). The Windows sockets facilities support a single communication domain: the Internet domain, used by processes which communicate using the Internet Protocol Suite.

Sockets are typed according to the communication properties visible to a user. Applications are presumed to communicate only between sockets of the same type, although nothing prevents communication between sockets of different types if the underlying communication protocols support this.

Two types of sockets currently are available to a user. A stream socket provides for the bidirectional, reliable, sequenced, and unduplicated flow of data without record boundaries. A datagram socket supports bidirectional flow of data which is not promised to be sequenced, reliable, or unduplicated. That is, a process receiving messages on a datagram socket may find messages duplicated and possibly in an order different from the sending order. An important characteristic of a datagram socket is that record boundaries in data are preserved. Datagram sockets closely model the facilities found in many contemporary packet-switched networks such as Ethernet.

For more information about Windows sockets, see the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


File Mapping

File mapping enables a process to treat the content of a file as if it were a block of memory in the process's address space. Therefore, instead of using file input and output (I/O) operations, the process can use simple pointer operations to examine and modify the contents of the file.

The Win32® API enables two or more processes to access the same file-mapping object. Each process receives a pointer to memory in its own address space. With this pointer, the process can read or modify the contents of the file.

There are three ways an application can share a file-mapping object created in one process with another process:

  • Inheritance. The first process creates the file-mapping object, and then allows the handle of the object to be inherited by a child process.
  • Named file mapping. The first process creates the file-mapping object with a well-known name (which can be different from the file name). The second process opens the file-mapping object by specifying the well-known name. Alternatively, the first process can create a file-mapping object with a unique name and communicate that name to the second process through some other IPC mechanism (named pipe, mailslot, and so on).
  • Handle duplication. The first process creates the file-mapping object, and then passes the handle of the object to the second process. The second process then duplicates the handle to gain access to the shared memory. The original process can communicate the file-mapping handle to the second process through one of the other IPC mechanisms (named pipe, mailslot, and so on).

When two or more processes have read/write access to a shared memory block, they must use some sort of synchronization object, such as a semaphore, to prevent data corruption in a multitasking environment.

File mapping is quite efficient and also provides operating system supported security attributes that can help prevent unauthorized data corruption. File mapping can be used only between processes on a local computer; it cannot be used over a network. An application can, however, create a file-mapping object to a file on a remotely mounted volume.

For more information about file mapping, see "Interprocess Communications" in the "Windows Base Services" section of the Microsoft Platform SDK.


Shared Memory

The Win32 API uses a special case of file mapping to provide shared memory access between processes. If you specify the system swap file when creating a file-mapping object, the file-mapping object is treated as a shared memory block. Other processes can access the same block of memory by opening the same file-mapping object (see File Mapping ). Because shared memory is implemented with file mapping, it supports security access attributes and can operate only between processes running on the same computer.

For information about shared memory, see "General Library" in the "Windows Base Services" section of the Microsoft Platform SDK.


Anonymous Pipes

An anonymous pipe, also called an unnamed pipe, enables related processes to transfer information back and forth as if they were reading from and writing to a file. Typically, anonymous pipes are used for redirecting the standard input and output (I/O) of a child process so that it can exchange data with its parent process.

To use an anonymous pipe, the parent process typically creates the pipe and then allows its read and write handles to be inherited by a child process. The parent process writes data to the pipe; the child process can read the data from the other end of the pipe. Likewise, the child process can write data to the pipe and the parent process can read the data from its end of the pipe. A parent process can also create two or more child processes that inherit the read and write handles to an anonymous pipe. Those child processes can use that pipe to communicate with each other directly, without going through the parent process.

Anonymous pipes cannot be used over a network, nor can they be used between unrelated processes.

For more information about anonymous pipes, see "Interprocess Communication" in the "Windows Base Services" section of the Microsoft Platform SDK.


Named Pipes

Named pipes are used to transfer data between processes, similarly to anonymous pipes. However, unlike anonymous pipes, named pipes can operate between unrelated processes and across a network between computers. Typically, a server process creates a named pipe with a well-known name. Client processes that can get the name of the pipe can open the other end of the pipe, subject to access restrictions specified by the pipe's creator. After they are connected, the server and client can exchange data by performing read and write operations on the pipe. Alternatively, the pipe creator can create a pipe and let a child process inherit the handle to the pipe, or it can create a pipe with a unique name and communicate that name to the client through some other interprocess communications (IPC) mechanism.

In a Microsoft BackOffice environment, named pipes have the following characteristics:

  • Shared common functionality, such as caching, with the other file systems. Manipulation of named pipes is similar to reading and writing to file handles. Remote access to named pipes is provided through the network redirector. Processes on the local computer can use named pipes to communicate with each other without going through networking components.
  • Working with named pipes is just like working with file I/O. You can use the same file I/O APIs and simply pass in the named pipe handles. Named pipes also support impersonation and asynchronous execution. Asynchronous execution, known as overlapped I/O, makes it possible for one pipe to simultaneously read and write data and for a single thread to perform simultaneous I/O operations on multiple pipe handles. This enables a single-threaded server process to efficiently handle communications with multiple client processes.

For more information about named pipes, see "Interprocess Communication" in the "Windows Base Services" section of the Microsoft Platform SDK.


Dynamic-Link Libraries

You can build a Win32-based dynamic-link library (DLL) so that its global data is shared with all processes that call the DLL. Therefore, cooperating processes can call the DLL to examine and modify global data owned by the DLL. For example, process A calls a DLL function with data that the DLL stores in its global data space. Process B calls another DLL function that retrieves that data. Because of the multitasking nature of the Win32 API, the DLL would have to use a semaphore or another synchronization object to control access to the shared memory.

Although shared global data can be used in a DLL, Win32 file mapping is recommended for shared memory. File mapping is more efficient and provides the additional benefit of access protection (see File Mapping). For example, a client can be limited to read-only access to a file-mapping object.

For information about dynamic-link libraries, see "Executables" in the "Windows Base Services" section of the Microsoft Platform SDK.


About Remote Procedure Call

Microsoft remote procedure call (RPC) represents the convergence of three powerful programming models: the familiar model of developing C applications by writing procedures and libraries; the model that uses powerful computers as network servers to perform specific tasks for their clients; and the client/server model, in which the client usually manages the user interface while the server handles data storage, queries, and manipulation. When you write a client/server application, you must provide the layer of code that manages network communication. RPC tools provide this layer for you.

As a tool for creating distributed applications, RPC provides the following benefits:

  • A familiar and popular programming model. You can easily turn functions into remote procedures, which simplifies the development and test cycles. Also, the Microsoft implementation is compatible with both client and server applications.
  • A method of hiding many details of the network interface from the developer. You don't need to understand specific network functions or low-level network protocols to implement powerful distributed applications.
  • A solution to the data-translation problems that occur in heterogeneous networks; individual applications can ignore this problem.
  • A scalable approach. As a network grows, applications can be distributed to more than one computer on the network.

When developing client/server applications using RPC, you must perform the following tasks:

  • Specify the protocol sequences that the server application will use to communicate with clients.
  • Enter the server into a listening mode for client requests.
  • Have the client application define the function interfaces using the Interface Definition Language (IDL) and compile the IDL file using the MIDL compiler.
  • Have the client application use automatic binding or application-managed binding (manage binding handles, and so on).

For more information about Microsoft RPC, see the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Programming Requirements and Recommendations

This section presents an overview of how to design applications that cleanly integrate with the Microsoft® BackOffice® components and perform efficiently in a Microsoft® Windows® client/server environment. The requirements and recommendations presented in this section enable you to ensure that your application takes advantage of the features provided by the BackOffice components.

Note You are not required to implement all of these recommendations in your application to obtain the Designed for Microsoft BackOffice logo (located at http://www.microsoft.com/backoffice/designed on the Internet); however, it is suggested that you seriously consider using the guidelines, which may become requirements in the future.

Server Application Requirements and Recommendations

The requirements for your server application are:

  • To run as a Microsoft® Windows NT® Server service.
  • To be network-independent.
  • To support the Windows NT Unified Logon.
  • To be installable using Microsoft® Systems Management Server (SMS).

The recommendations for your application are:

  • To support Automation (formerly known as OLE Automation).
  • To support remote administration.
  • To support long file names and the universal naming convention (UNC).
  • To integrate with Microsoft® Internet Information Server.
  • To support other recommendations such as messaging server applications, Mailbox-Agent objects, Mailbox-Gateway objects, and Open Data Services (ODS).

Client Requirements and Recommendations

The requirements for your client application are:

  • To execute as a 16-bit Windows operating system interface-based client.
  • To provide client/server connectivity (such as correct messaging, SQL Server, or SNA APIs and functions).
  • To be installable through SMS.

The recommendations for a client application are:

  • To be developed as a 32-bit Windows operating system interface-based client.
  • To address MAPI design issues.
  • To address database connection issues, such as using ODBC/DRDA drivers to access host data; using stored triggers, procedures, and cursors; using Open Data Services (ODS); using SQL Distributed Management Objects (SQL-DMOs); and using integrated security concepts with SQL Server.


Server Requirements for BackOffice

This section describes the requirements your server application should attempt to satisfy to be an effective BackOffice application.


Running as a Windows NT Server Service

A Windows NT Server service is an executable object installed in the registry database and maintained by the service control manager. The services database includes information that determines whether each installed service is started on demand, or started automatically with Windows NT Server. In either case, the service starts without user intervention. The database can contain logon and security information for a service so that it can run even though no user is logged on. The database also enables system administrators to customize security requirements for each service and thereby control access to it.

Running as a Windows NT Server service allows a server application to impersonate a client while accessing objects and performing actions on behalf of the client. This capability ensures that the server application can act on behalf of a client without running with an inappropriately high privilege level. It also ensures that the server application will not be able to perform actions that would be denied the client directly.

By starting automatically, a server application implemented as a service is guaranteed to be available so long as Windows NT Server is running. Moreover, related services can be started easily and, where appropriate, automatically.

Finally, implementing a server application as a service allows the application to be installed and controlled using standard user and Win32® APIs. Such a service can be started and stopped both locally and remotely, providing network administrators an easy and consistent way to control the service across the network.


Network Independence

Developing a network-independent server application eliminates the complexities of network data transfer from the development process, and allows you to concentrate on the application's functionality. Similarly, a client application can be designed to take advantage of standard, transport-independent interprocess communications (IPC) interfaces. This helps ensure that the client and server applications can run on a wide variety of network platforms with little or no modification.

Windows NT currently supports several sets of networking APIs that provide this transport independence: remote procedure call (RPC), the Windows Sockets API, named pipes, and the OLE/Component Object Model (COM).

Remote Procedure Call

The Win32 API provides remote procedure calls (RPCs) to enable applications to call functions remotely. With RPC, communication with other processes becomes as easy as calling a function. RPC operates between processes on a single computer or on different computers on a network. One way to think of RPC is as a DLL that works on a network.

The RPC provided by the Win32 API is compliant with the Open Software Foundation (OSF) Distributed Computing Environment (DCE). This means that RPC applications written using the Win32 API are able to communicate with other RPC applications running with other operating systems that support DCE. RPC automatically supports data conversion to account for different hardware architectures and for byte-ordering between dissimilar environments.

For more information about RPC, see About Remote Procedure Call.

Windows Sockets API

The Windows Sockets API is intended to provide a single API to which application developers can program and multiple network software vendors can conform. Furthermore, in the context of a particular version of Microsoft Windows, it defines an application binary interface such that an application written using the Windows Sockets API can work with a conforming protocol implementation from any network software vendor. This specification defines the library calls and associated semantics to which an application developer can program and which a network software vendor can implement, allowing an effective exchange of data from client to server.

For more information about the Windows Sockets API, see Windows Sockets.

Named Pipes

A named pipe is a one-way or two-way communication mechanism between a server process and one or more client processes. Under Windows NT, named pipes are implemented as a file system and share many characteristics associated with files with respect to use and manipulation.

For more information about named pipes, see "Interprocess Communication" in the "Windows Base Services" section of the Microsoft Platform SDK.


OLE/Component Object Model

The OLE/Component Object Model (COM) is designed to allow clients to communicate transparently with objects, regardless of whether those objects are running within the same process, on the same machine, or on a different machine. From a client's point of view, all objects are accessed through interface pointers. OLE/COM does not specify the component's structure; only its interaction, relegating concerns about the internal structure of a component to programming languages and development environments. Generally, programming environments do not have uniform standards for working with objects outside of their immediate application. OLE/COM, through language-independent interfaces, picks up where programming languages leave off to provide network-wide interoperability.

The OLE/COM components can perform cross-process communication within the same machine. To support communication between objects across different machines, components such as a global name space, global registry, and object store must be developed. To support this initiative, Microsoft will be developing and providing distributed COM (DCOM) in the future containing these features.

For more information on OLE/COM and custom interfaces, see the "COM and ActiveX Object Services" section of the Microsoft Platform SDK.


Support for Windows NT Unified Logon

The Microsoft Windows NT Unified Logon allows the client to log on one time to the system and use the Windows NT security system to authenticate the user for network and application resources. One objective of the Windows NT security model is to ensure that the programs that a user runs have no more access to objects than the user does. When a program or process runs on the user's behalf, it is said to be running in the security context of that user. The security context controls what access the subject has to objects or system services. Generally, when a subject calls an object service through a protected subsystem, the subject's token is used within the service to determine who made the call and to decide whether the caller has sufficient access authority to perform the requested action.

Windows NT allows one process to take on the security attributes of another through a technique called impersonation. For example, a server process typically impersonates a client process to complete a task involving objects to which the server does not normally have access. Impersonation is useful in a distributed computing environment when servers must pass client requests to other server processes or to the operating system. In this case, a server impersonates the client's security context. Other server processes can then handle the request as if it had been made by the original client.

Most Windows NT communication mechanisms, such as RPCs and named pipes, support the Unified Logon paradigm using the object's security context. Others, such as Windows Sockets, do not support the transference of security. Additional APIs for impersonation were introduced with Windows NT version 3.51.

For more information about communications techniques in a secure environment, see the "Windows Base Services" section of the Microsoft Platform SDK.


Installable Using Microsoft Systems Management Server

Server applications that support Microsoft Systems Management Server (SMS) are easier for customers to deploy, manage, upgrade, and inventory. An installation or setup application using SMS must support the following features. For more information see the Microsoft SMS documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.

Package Definition File

A package definition file (PDF) is an ASCII text file containing predefined Workstation, Sharing, and Inventory property settings for a package. A PDF follows the standard initialization file format and has specific keys and entries that are used by the system to set the properties of a package.

Unattended Setup

Client applications you develop must not require user input during the installation, removal, or maintenance of the application. Any information or options required by the setup program should be supplied by command-line switches to the program, or should be provided in a configuration file that is read by the program at run time or by some other means such as the Windows NT registry. Because multiple packages can be installed by SMS at one time, no individual package installation should force a restart of the operating system as part of its installation program. To copy system files that may be in use, setup programs typically construct a batch file containing operations that must be performed during a restart.

Provision for Uninstall

Uninstall facilitates a system's software upgrades, retirement, recalls, version conflicts, and so on. The setup program must include a provision to support the removal of the application-owned components and clean up environment settings as well as registry entries. The setup program ideally would provide a switch or option as part of the setup procedure supporting the Uninstall capability.

Reporting of Status to SMS Using a Status MIF File

To add or maintain items in an SMS database, the SMS system uses data in the Management Information Format (MIF). MIF files are used to maintain (create, update, and delete) the machine objects. Using ASCII text files with the MIF format, you can also add, update, or delete custom objects and groups from the SMS database.


Server Recommendations

This section describes the recommendations your server application should attempt to satisfy to be an effective Microsoft BackOffice application.


Supporting Automation

Using Automation (formerly known as OLE Automation) enables the developer to create an instance of a programmable object—a software component that exposes its properties and methods—and reference and manipulate it with tools that support Automation. Automation uses the OLE/Component Object Model. Use Automation to:

  • Create applications and programming tools that expose objects.
  • Create and manipulate objects exposed in one application that were originally created in another application.
  • Create tools that access and manipulate objects. These tools can include embedded macro languages, external programming tools, object browsers, and compilers.

The objects an application or programming tool exposes are called Automation objects. Applications and programming tools that access those objects are called Automation controllers. Applications and other software packages define and expose objects, which, in turn, can be acted upon by Automation controllers. Type information describes the exposed objects, and can be used by Automation controllers at either compile time or run time.

For more information on Automation, see the "COM and ActiveX Object Services" section of the Microsoft Platform SDK.


Supporting Remote Administration

Supporting remote administration allows for single-seat administration of multiple servers within an enterprise environment. Even though servers within an organization may be spread throughout the world on a wide area network (WAN), it is possible to architect applications to administer remote services running on remote servers. To create server applications that can be administrated remotely, you should:

  • Use the Windows NT registry to store configuration parameters.
  • Use event logging to audit actions, failures, errors, and so on.
  • Create a separate user interface (UI) client portion that communicates to a server portion by way of remote procedure call.
  • Support delayed connections.


Supporting Long File Names and UNC

Microsoft Windows NT and Windows 95 now provide the capability to incorporate long file names in system administration and application development, and support the universal naming convention (UNC) for seamless integration in networking environments.

Long File Names

Long file names significantly expand and increase the 32-bit Windows operating system functionality that previously was limited by the 8.3 file name length restriction of the older 16-bit Windows operating system.

The following general guidelines apply to all file systems supported within the Windows operating system. An application that follows these guidelines can create valid names for files and directories regardless of the file system in use:

  • Use any character in the current code page for a name, but not a path separator, a character in the range 0 through 31, or any character disallowed by the file system. A name can contain characters in the extended character set (128–255).
  • Use the backslash (\) and/or the forward slash (/) to separate components in a path.
  • Use a period (.) as a directory component in a path to represent the current directory and to separate components in a directory name or file name.
  • Use two consecutive periods (..) as a directory component in a path to represent the parent of the current directory.
  • Do not use the following characters in directory names or file names, because they are reserved for Windows: < > : " / \ |
  • Do not use reserved words, such as aux, con, and prn, as file names or directory names.
  • Process a path as a null-terminated string. The maximum length for a path is given by MAX_PATH. The Unicode versions of the CreateDirectory, FindFirstFile, GetFileAttributes, and SetFileAttributes functions allow paths to exceed the MAX_PATH length if the path has the \\?\ or \\?\UNC\ prefix. These prefixes turn off path parsing. Use the \\?\ prefix with paths for local storage devices and the \\?\UNC\ prefix with paths using the UNC format. An example of a UNC path is \\machine\sharename.
  • Do not assume case sensitivity, because not all file systems distinguish between cases.

Universal Naming Convention

Supporting the UNC paths when dealing with file names is another way for an application to work seamlessly in a network environment. UNC paths allow logical connections to network devices without the need to specifically reference a network drive letter. The system will be able to locate the network server and path with the UNC name even over a modem connection. The UNC describes network servers and share points on those servers. UNC names start with two backslashes followed by the server name. All other fields in the name are separated by a single backslash.


Integrating with Internet Information Server

The principal API used to communicate with Microsoft® Internet Information Server (IIS) is Internet Server API (ISAPI). ISAPI for Windows NT can be used to write applications that users of the World Wide Web can activate by filling out an HTML form or clicking a link in an HTML page on your Web server. The remote application can then take the user-supplied information and do almost anything with it that can be programmed, and then return the results in an HTML page or post the information in a database.

ISAPI can be used to create applications that run as DLLs on your Web server. If you have used Common Gateway Interface (CGI) scripts, you will find that the ISAPI applications have much better performance because they are loaded into memory at server run time. They require less overhead because each request does not start a separate process. ISAPI extension DLLs are essentially in-process CGI applications. A client uses ISAPI extensions just as it would execute CGI applications, but instead of referencing them as "http://scripts/cgi.exe?Param1+Param2", a client would use "http://scripts/isapi.dll?Param1+Param2".

Because ISAPI applications and filters are implemented as DLLs, they are inherently single-process and can support thread pooling whereby the Internet Information Server will call out to the extension DLL. DLLs also require much less overhead for instantiation compared to a process. In addition, function calls are direct and involve no process transition or intermediate steps. Multiple extension DLLs can be loaded and called simultaneously.

To create ISAPI extension DLLs
  1. Export and implement GetExtensionVersion. This provides the initial entry point from IIS into your extension DLL and is used to provide the version and description of your extension.
  2. Export and implement HttpExtensionProc. This is the main entry point into the functionality for your extension. It is equivalent to main( ) in a CGI application. This function is called once per request and can be called simultaneously from multiple threads. For this reason your extension DLL must be thread-safe.
  3. Use the EXTENSION_CONTROL_BLOCK data structure. This data structure contains data about the client request, and provides four callback functions that your extension DLL can use. These callback functions are:

    ReadClient, used to obtain data from the client's HTTP (Hypertext Transfer Protocol) request.

    WriteClient, used to send data to the HTTP client from a buffer.

    GetServerVariable, used to obtain information about the client connection or the server itself.

    ServerSupportFunction, which provides some general-purpose functions as well as functions that support HTTP. The basic functions include client URL redirection, return of another URL's data, and return of detailed header information.

ISAPI extension DLLs can also be combined with the Internet Database Connector to create highly interactive sites. ISAPI allows preprocessing of requests and post-processing of responses, permitting site-specific handling of HTTP requests and responses. ISAPI filters can be used for applications such as customized authentication, access, compression, encryption, logging, or client request analysis.

For more information about ISAPI, see the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Other Recommendations for Development of Server Applications

This section presents additional development techniques you can incorporate into your application design process for a BackOffice server application.

Messaging Server Applications

Server applications can be developed to extend the basic functionality of messaging and workgroup software applications such as Microsoft Exchange Server. They can be used to provide a broad range of services, from mail gateways and voice mail to document management, content indexing, and electronic newspapers. Server applications communicate with Microsoft Exchange Server components through MAPI. This communication includes actions such as using the address book, accessing information stores (including public folders), and transferring messages.

Most server applications are either mailbox agents or gateways. As such, a server application is represented in the Microsoft Exchange Server directory as either a Mailbox-Agent or a Mailbox-Gateway object.

Mailbox-Agent Objects

A server application that has its own mailbox within Microsoft Exchange Server is a mailbox agent. A typical mailbox agent uses its mailbox to communicate with mail users, gather processing requests, and distribute results. There are three general Mailbox-Agent object configurations a server application can employ:

  • It can use its own mailbox. Most server applications are either mailbox agents or gateways, which have their own mailboxes in information stores on Microsoft Exchange Server.
  • It can use other mailboxes. Server applications can use mailboxes other than their own to delegate access and for privileged access.
  • It can use no mailbox. Every directory object also has a mailbox. If a server application does not need a mailbox, the server application can be configured to have no mailbox at all.

Mailbox-Gateway Objects

A gateway is an interface that connects electronic messaging systems that have different message and address formats. In its simplest form, a gateway receives a mail message, translates it from one messaging system's format to another, maps addresses between the two systems, and then delivers the translated message. Messages transferred by the gateway appear to come directly from the originating mail system. A gateway can translate messages between mail systems within a single organization or between an organization and an outside mail system.

A Microsoft Exchange Server gateway is a client application of MAPI. This means that it uses MAPI interfaces, methods, and properties to communicate with Microsoft Exchange Server. A gateway is also a server application for Microsoft Exchange Server; as such, it should be implemented as a service of Microsoft Windows NT Server.

For optimum performance, a gateway should be tightly integrated with MAPI, Windows NT Server, and the Microsoft Exchange Administrator program.

Open Data Services

Microsoft Open Data Services (ODS) provides a server API that consists of C functions and macros used for creating two types of server applications:

  • Applications that are initialized as ODS servers and that support user connections and user queries.
  • Applications called extended stored procedures that are added directly to SQL Server and accessed by making procedure calls to SQL Server.

Applications created with ODS can interact with SQL Server database clients, with SQL Server database servers, and with any other elements of a network environment that you define.

This interaction allows you to create powerful server applications that can:

  • Provide extensions to SQL Server by integrating features from your network environment whenever certain events occur within SQL Server. For example, you can create extension functions that take specific actions based on updates to SQL Server tables, launch programs that are external to SQL Server, or exchange data with an application external to SQL Server. You can even make these functions transparent to SQL Server users.
  • Provide gateways to non-SQL Server database environments. ODS server applications can connect to relational databases to perform general-purpose data access, or to nonrelational data sources to perform application-specific tasks.


Client Requirements for BackOffice

This section describes the requirements your application should attempt to satisfy to be an effective Microsoft BackOffice client application.

You must ensure that your application executes as a 16-bit Windows operating system interface-based client. Many users have the 16-bit Windows 3.x operating system installed on their computers, and to interact with server applications supporting the features outlined in this reference, client applications must also use the 16-bit Windows 3.x operating system.

Developers should note that Microsoft strongly encourages its customers to make the transition to 32-bit operating systems such as Windows NT and Windows 95. For more information on features provided by Microsoft's 32-bit operating systems, see 32-Bit Windows Operating System Interface-Based Client.

Each server application within the BackOffice family has a set of APIs that are intended to be called by client applications requesting functions and information from that BackOffice server application. For Microsoft Exchange Server, MAPI is the predominant API used by messaging clients for communication. Microsoft SQL Server provides several different methods for client applications to communicate requests and transfer information. Microsoft SNA Server has several APIs that can be used to connect with client applications.


Messaging Clients in a BackOffice Environment

MAPI provides a comprehensive set of features that separate the programming interface used by the front-end messaging client applications from the programming interface used by the back-end service providers. MAPI thus removes any programming dependencies placed on the application by the messaging system. In the BackOffice family, MAPI provides the primary link to communication with Microsoft Exchange Server.

MAPI is a messaging architecture that enables multiple applications to seamlessly interact with multiple messaging systems across a variety of hardware platforms. The interfaces are used to create and access diverse messaging applications and messaging systems, offering a uniform yet separate environment for development and use and providing true independence for both.

In a BackOffice environment, MAPI client applications are divided into three categories:

  • Messaging-aware applications, which do not require the services of a messaging system, but include messaging options as an additional feature. For example, a word-processing application can add a Send command to its File menu, enabling the user to send a document to another user.
  • Messaging-enabled applications, which require the services of a messaging system and typically run on a network or an online service. An example of a messaging-enabled application is Microsoft Exchange Server.
  • Messaging-based workgroup, or workflow applications, which require full access to a wide range of messaging system services, including storage, addressing, and transport services. These applications are designed to operate over a network without users having to manage the applications' network interaction. Examples include workflow automation programs and bulletin board services.

MAPI supports these types of client applications by providing in its subsystem different levels of programming interfaces. Most client applications will use one of the following client APIs: Active Messaging Library, Active Messaging Rendering Library, Simple MAPI, or CMC MAPI. However, some clients can use more than one client API. These clients will use MAPI for some tasks and a simpler API for others. The MAPI architecture makes this fairly easy by providing several API functions for converting between the environments.

The Microsoft® Active Messaging Library exposes messaging objects for use by tools supporting Automation, such as those applications created in Microsoft® Visual Basic® and Visual C++®. The messaging library enables developers to quickly and easily add to a Visual Basic application the ability to send and receive mail messages and to interact with folders and address books. The developer can create programmable messaging objects, then use their properties and methods to meet the needs of an application. When messaging objects are combined with other programmable objects exposed by Microsoft® Access, Microsoft® Excel, and Microsoft® Word, the developer can build custom applications that, for example, would allow users to extract information from a database, copy it to a spreadsheet for analysis, and then create a report and mail the report to several users. With these powerful building blocks, the developer can create custom applications that cover entire line-of-business needs.

The Microsoft Active Messaging Rendering Library is associated with the Active Messaging Library, and the two are interdependent. Active Messaging Rendering entails displaying Active Messaging objects and collections over the World Wide Web.

Automation defines programmable objects that can be used to extend the capabilities of clients such as Microsoft Schedule+. The scheduling Automation interface enables the developer to create instances of programmable scheduling objects. After the new objects are created, they can be referenced with tools that support Automation, such as Visual Basic and Visual C++.

For more information about MAPI and Active Messaging, see the "Database and Messaging Services" section of the Microsoft Platform SDK. Information about the Schedule+ Automation interface can be found under "Microsoft Exchange Server" in the "Database and Messaging Services" section of the Platform SDK.


Microsoft SQL Server Client Issues

Microsoft SQL Server is a powerful structured query language (SQL) database server that enables the development of robust and efficient, information-intensive applications.

Developers can write applications for SQL Server by programming with DB-Library for C, the C-language version of the communication library for SQL Server, or with DB-Library for Visual Basic, the Visual Basic version of the communication library for SQL Server.

DB-Library for C is an API that consists of C functions and macros that allow an application to interact with SQL Server. Included are functions that send Transact-SQL statements to SQL Server and functions that process the results of those statements. Other functions handle errors and convert data.

DB-Library for C offers a rich set of functions for:

  • Opening connections.
  • Formatting queries.
  • Sending query batches to the server and retrieving the resulting data.
  • Using scrollable cursors.
  • Bulk-copying data from files or program variables to and from the server.
  • Controlling two-phase commit operations between several participating SQL servers.
  • Executing stored procedures or remote stored procedures.

In addition to DB-Library, SQL Server supports the Microsoft Open Database Connectivity (ODBC) call-level API. ODBC enables applications for Windows, Windows NT, and Windows 95 to access multiple data sources, including a wide range of relational databases and local indexed sequential access method (ISAM) data. In most cases, DB-Library and ODBC are equally capable of creating SQL Server client applications. ODBC enables applications to access more data sources, while DB-Library provides equivalent functionality in multiple-client environments, including the MS-DOS operating system specialized support for SQL Server (such as bulk copy and two-phase commit).

For more information about DB-Library and ODBC, see "Microsoft SQL Server Programmer's Toolkit" and "ODBC" in the "Database and Messaging Services" section of the Microsoft Platform SDK.

Using Embedded SQL allows programmers to place SQL statements into programs written in a standard programming language, which is termed the host language. The Embedded SQL approach, using programming statements similar to Transact-SQL, is more concise than the function-call approach and is tightly coupled to the existing database structure. Because the SQL statements are directly included in the source code, Embedded SQL programs are usually special-purpose applications. Embedded SQL is well suited for environments where the programmer is also in control of the database structure. However, it is less flexible for environments where the database structure is changing or is not known in advance.

For more information about Embedded SQL, see the Embedded SQL for C 4.22 SDK on the Microsoft Developer Network Development Library compact disc.


Microsoft SMS Server Client Issues

In the Microsoft Systems Management Server (SMS) system, the site database for a primary site stores the inventory and configuration information for itself and sites below it in the site hierarchy. The SMS API enables a client application to retrieve, add, and remove data in the SMS database.

For more information, see the Microsoft SMS documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


About Systems Management Server Client Functionality

In addition to using the SMS API for interaction with the Microsoft Systems Management Server (SMS) database, a client application should support SMS functionality that allows the application to be more easily deployed, managed, upgraded, and inventoried. An installation or setup application using SMS must support the following features. For more information see the Microsoft SMS documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.

Package Definition File

An ASCII text file containing predefined Workstation, Sharing, and Inventory property settings for a package. A PDF follows the standard initialization file format and has specific keys and entries that are used by the system to set the properties of a package.

Unattended Setup

A client application you develop must not require user input during its installation, removal, or maintenance. Any information or options required by the setup program should be supplied by command-line switches to the program, or should be provided in a configuration file that is read by the program at run time or by some other means such as the Windows NT Registry. Because multiple packages can be installed by SMS at one time, no individual package installation should force a restart as part of its installation program. To copy system files that may be in use, setup programs typically construct a batch file containing operations that must be performed during a restart.

Provision for Uninstall

Uninstall facilitates a system's software upgrades, retirement, recalls, version conflicts, and so on. The setup program must include a provision to support the removal of the application-owned components and clean up environment settings as well as registry entries. The setup program ideally would provide a switch or option as part of the setup procedure supporting the Uninstall capability.

Reporting of Status to SMS Using a Status MIF File

To add or maintain items in an SMS database, the SMS system uses data in the Management Information Format (MIF). MIF files are used to maintain (create, update, and delete) the machine objects. Using ASCII text files with the MIF format, you can also add, update, or delete custom objects and groups from the SMS database.


Microsoft SNA Server Client Issues

Microsoft SNA Server is a systems network architecture (SNA) gateway for connecting desktops on a local area network (LAN) to midrange and mainframe computers (such as the IBM AS/400). Several different industry-standard SNA APIs have evolved for development of integrated SNA applications and hosts:

  • WOSA APIs or Function Management Interface (FMI) for SNA Client
  • SNA Server Client APIs
  • SNA Server compatibility APIs for IBM PC Support or Client Access/400

To provide one common set of APIs to port applications from various operating systems to Windows NT, Windows 95, and Windows version 3.x, a Windows SNA specification was created. As a direct result of this work, the Windows APPC, Windows CPI-C, and Windows logical unit application (LUA) specifications were developed. All of these Windows SNA specifications define a set of extensions that allow for asynchronous communication. Asynchronous call completion returns the initial call immediately so the application can continue with other processes. A program that issues a call and does not regain control until the operation completes is not able to perform any other operations. Windows NT also supports using Win32® events for supporting asynchronous calls.

Programs written to use Windows APPC can exchange data with programs written to use other implementations of APPC that adhere to the SNA LU type 6.2 or later architecture. Windows APPC adds to this functionality by providing a set of extensions for asynchronous communication in addition to the full complement of APPC features.

Windows CPI-C is compliant with CPI-C version 1.2 or later, which allows applications developed using the CPI-C Systems Application Architecture API to establish a conversation to exchange data and control information flow between two programs. CPI-C version 1.2 or later provides the following functionality:

  • Support for automatic parameter conversion
  • Communication with non-CPI-C programs
  • Local/remote transparency as well as X/Open CPI-C support for nonblocking calls
  • Ability to accept multiple conversations
  • Support for data conversion (beyond parameters)
  • Support for security parameters

Windows CPI-C further adds to this functionality by providing a set of extensions for asynchronous communication, in addition to the full complement of supported features in CPI-C version 1.2 or later (with the exception of resource recovery).

The conventional LUA programming interface is an API that allows you to write LUAs to communicate with host applications. The Windows LUA interface is provided at the request/response unit (RU) and session levels, allowing programmable control over the SNA messages sent between your communications software and the host. It can be used to communicate with any of the logical unit (LU) types 0, 1, 2, or 3 at the host; the application must send the appropriate SNA messages required by the host.

The Function Management Interface (FMI) provides applications with direct access to SNA data flows and information about SNA control flows by means of status messages, while shielding them from the full complexities of SNA protocol handling. It is particularly suited to the requirements of applications emulating 3270-type controllers.

For more information about Microsoft SNA Server and its APIs, see the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.

Developers who want to create applications that integrate a 3270 emulator with SNA Server should use the 3270 Emulator Interface Specification. This specification defines the initialization, message passing, and termination procedures required for 3270 emulator and SNA Server communication.

SNA Server version 2.11 and later supports the EHNAPPC API, which is the Windows-based APPC API supported by IBM's PC Support and Client Access/400 (CA/400) products. IBM has provided the EHNAPPC API to its independent software vendor (ISV) community as the way to write Windows-based applications that integrate with the AS/400. There are estimated to be more than 60 applications that use this API as a way to connect to the AS/400 data and applications. These ISV applications will work unchanged with SNA Server version 2.11 and later versions.


Client Recommendations

This section describes the recommendations your client application should attempt to satisfy to be an effective Microsoft BackOffice application. These recommendations are provided as a guide during the development of your application and stress important programming concepts that may become requirements. A 32-bit Windows operating system interface-based client allows you to fully utilize all of the functionality inherent within the BackOffice environment. Using MAPI allows clients to completely integrate with MAPI-compliant messaging applications and servers such as Microsoft Exchange Server. Finally, an important programming method is to use the appropriate database techniques for manipulating and retrieving data from ODBC-compliant databases such as SQL Server.


32-Bit Windows Operating System Interface-Based Client

With the release of Windows NT and Windows 95 as 32-bit operating systems, there now exists the potential to create powerful 32-bit-based client applications. The Win32 API provides a unified development API on the Windows NT and Windows 95 operating systems, allowing a single set of source code to be used on multiple platforms (Intel-based, MIPS, Alpha AXP, PowerPC). By taking advantage of the Win32 API, a client application can use the following features.

Structured Exception Handling

Structured termination handling ensures that whenever a guarded body of code is executed, a specified block of termination code is also executed, regardless of how the flow of control leaves the guarded body. Structured exception handling is made available to developers primarily through compiler support. For example, the Microsoft compilers provided with the Platform SDK support the try keyword that identifies a guarded body of code, and the except and finally keywords that identify an exception handler and a termination handler, respectively.

The Registry

The registry is used for storing and retrieving configuration data on a per-user, per-machine, and per-application basis. Because the data is stored in a binary format, an application must use the registry functions to manipulate the registry. The registry stores data in a hierarchically-structured tree with each node in the tree called a key. Each key can contain both subkeys and data entries called values.

Multitasked Thread Support

To the developer, multitasking thread support offers the ability to create applications that use more than one process and to create processes that use more than one thread of execution. It is useful for a process to have multiple threads in situations where the application has several tasks to run concurrently. Multiple threads can be a convenient way to structure a program that performs several similar or identical tasks, and can be especially beneficial to server applications in the following cases:

  • For communications-bound tasks. The portion of a server application that provides services to clients should be implemented in one or more threads separate from the portion of the application that performs processing on behalf of the client or that connects to an auxiliary process.
  • For tasks within a system of varying priority. The portion of a server application devoted to CPU-intensive tasks should be implemented using different threads from the portions devoted to I/O-intensive tasks to ensure that higher-priority tasks receive scheduling preference.

Synchronization

To coordinate multiple threads of execution, synchronization mechanisms, such as wait functions and synchronization objects, and overlapped input and output (I/O) operations are provided. Synchronization objects have handles that can be specified in one of the wait functions to coordinate the execution of multiple threads. Objects include events for notification, mutexes for mutually exclusive access to shared resources, and semaphores for limiting the number of threads that may simultaneously access a shared resource. Wait functions enable a thread to block its own execution. These functions do not return until a set of conditions specified by the wait function's parameters (time-out interval and handles of one or more synchronization objects) are satisfied.

Event Logging

Event logging provides a common repository for recording software and hardware events, as well as an interface with which to view them. Logging consumes resources: disk space and logging time. The event log is not intended to be used as a trace facility. You should log information about events that can be used to diagnose problems after they have occurred. Logging low-memory conditions, for example, can provide information about a problem that the system administrator can solve by adding more memory to the computer.

Performance Monitoring

Performance Monitor provides a mechanism for developers to add performance objects and counters for their applications and other software components, so that they can provide performance data to Windows NT Performance Monitor or to your customized performance monitoring programs. To add performance counters to the system, you must create an extended object. Your extended object is called when Performance Monitor collects data.


Design Issues for MAPI Clients

MAPI provides a consistent way for developers to work with and use different messaging systems in a seamless fashion. For BackOffice clients, using MAPI ensures that your application can efficiently access data from MAPI applications and servers, as well as use the broad functionality associated with MAPI.

Important design issues to consider when developing MAPI client applications include:

  • Accessing public folders. For most purposes, applications access public folders the same way they access private folders in private mailboxes using the MAPI interface. Subject to access restrictions, an application can browse the folders and items in the public store; read, delete, modify, and search for items; and create new public folders in the public folder hierarchy. Because they are addressable objects, public folders allow users to send messages directly to them. To develop applications that access public folders, you will use MAPI, Microsoft Exchange Server directory access functions, or Microsoft Exchange Server developer documentation public folder functions.
  • Using custom forms for applications. Custom forms are an important part of many applications that run in the Microsoft Exchange Server environment. When creating forms-based applications for Microsoft Exchange Server, the developer can interface with forms using MAPI. These interfaces offer the ability to define custom forms, install them in forms registries, and supply them to Microsoft Exchange Server users.
  • Extending the Microsoft Exchange Client. The basic Microsoft Exchange Client is included in the Windows 95 operating system as the core mail client. When drivers are loaded that set up the Windows 95 client to communicate with a Microsoft Exchange Server system, functionality specific to Microsoft Exchange Server clients is added to the Microsoft Exchange Client by making use of the client's extensibility interfaces.

For more information about using MAPI to extend your client application, see the "Database and Messaging Services" section of the Microsoft Platform SDK.


Database Connectivity Issues

Several techniques exist to efficiently connect to and manipulate data from Microsoft SQL Server. SQL Server supports a variety of approaches for integrating and optimizing your client application with local or distributed database servers.

ODBC/DRDA Drivers to Access Host Data

Many applications use the Open Database Connectivity (ODBC) programming interface to access local and server-based databases, while distributed databases on IBM hosts are usually managed through the Distributed Relational Database Architecture (DRDA) protocol defined by IBM.

SQL Server includes the StarSQL ODBC/DRDA drivers for Windows and Windows NT clients. With these drivers, applications designed to use the ODBC interface and structured query language (SQL) can access databases located on IBM hosts that use the DRDA protocol to manage distributed data, without requiring a host-based database gateway. These drivers allow ODBC-enabled applications (such as Microsoft Excel and Microsoft Access) to query, create, delete, and update tables in the following host databases: DB2 for MVS, SQL/DS for VM and VSE, and DB2/400 for OS/400.

Stored Procedures, Triggers, and Cursors

Microsoft SQL Server provides several mechanisms that can be used to optimize your application as well as take advantage of SQL Server's inherent functionality.

You can refine your applications by using stored procedures, which are compiled collections of SQL statements and control-of-flow language that execute very quickly. Stored procedures greatly enhance the power, efficiency, and flexibility of SQL Server, and dramatically improve the performance of SQL statements and batches. Stored procedures on other SQL Servers to which the client process is not in direct connection can be executed if the remote server has been set up to allow remote logins.

A trigger is a kind of stored procedure that goes into effect when you modify data in a specified table. Triggers are often created to enforce business rule consistency among logically related data in different tables. Triggers are automatic, working no matter what caused the data modification—a user's entry or an application action.

Server cursors allow individual row operations to be performed on a given results set or on the entire set. In SQL Server version 6.0 and later, ANSI SQL cursors are server-based. In earlier releases, cursors were provided only through the DB-Library and Open Database Connectivity (ODBC) cursor APIs. The addition of cursors to the server provides an efficient way for single-row operations to occur within a given results set. ANSI SQL cursors support only single-row cursors. Each fetch (move) will return only one row from the results set. Server cursors enhance the general use of relational databases by allowing row-level operations when set-oriented operations are impractical. In relational systems, set operations are preferred, to which cursors provide a powerful complement. Using cursors, multiple operations can be performed row by row against a results set with or without returning to the original table. In other words, cursors conceptually return a results set based on tables within the database or databases.

For more information about using stored procedures, triggers, and cursors, see "Microsoft SQL Server Programmer's Toolkit" in the "Database and Messaging Services" section of the Microsoft Platform SDK.

SQL Distributed Management Objects

SQL Distributed Management Objects (SQL-DMOs) are 32-bit Component Object Model (COM) objects for the Windows 95 and Windows NT operating systems. The SQL-DMO objects are Automation compatible. The SQL-DMO object model includes objects, properties, methods, and collections that are used to write programs that can administer multiple SQL Servers distributed across a network. SQL-DMO programs can range from simple Visual Basic scripts to complex Visual C++ applications. Using SQL-DMO you can access objects such as SQL Server devices, logins, language, remote servers, configuration, and security. You can also manage application environments such as backups and permissions, databases, indexes, tables, stored procedures, and triggers.

Integrated Security with SQL Server

Integrated security combines SQL Server login security with Windows NT security. This allows a network user to log in to a SQL Server without supplying a separate login identifier or password. Users can maintain one login identifier and password for both Windows NT and SQL Server. Integrated security lets SQL Server applications take advantage of Windows NT security features, including encrypted passwords, password aging, domain-wide user accounts, and Windows-based user administration. (For more information about these features, see your Windows NT Server documentation.)

Login security integration operates over network protocols that support authenticated connections between clients and servers. Such connections are referred to as trusted connections. Trusted connections include multiprotocol and named pipes sessions from other Windows NT-based workstations, from Windows for Workgroups-based clients, from Windows 95-based clients, and from Microsoft LAN Manager clients running under the Microsoft Windows or MS-DOS operating systems. Using the multiprotocol Net-Library, trusted connections can also be made over the NWLink IPX/SPX protocol from Windows version 3.1 clients using Novell software. (In this case, the user will be prompted for a Windows NT username and password at SQL Server connect time.)

For more information about Windows NT system security, see the "Windows Base Services" section of the Microsoft Platform SDK.


Developing Microsoft Exchange Server Applications

This section provides a brief overview of some of the important topics to consider when developing applications that interact with Microsoft® Exchange Server. For additional information about Microsoft Exchange Server functionality, development specifications, and guidelines, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Introduction to Microsoft Exchange Server

Microsoft® Exchange Server is a complete messaging and workgroup software solution that is appropriate in organizations ranging in size from several users at a single location, to large corporate enterprises distributed over a wide geographic area.

The Microsoft Exchange Server system is composed of three distinct elements—the user's workstation, the computer running Microsoft® Windows NT® Server, and the computer running Microsoft Exchange Server. Microsoft Exchange Server runs on Windows NT Server, which allows users of Microsoft Exchange Client applications access to several key services. These services include addressing and object information, information and forms storage, as well as message and information routing, object information exchange between systems, and information transfers to other systems.

The set of protocols and procedures central to the messaging architecture of the Microsoft Exchange Server system is the messaging application programming interface (MAPI). MAPI is a set of API functions and OLE interfaces that allows messaging clients, such as Microsoft Exchange Client, to interact with various message service providers, such as Microsoft Mail and Microsoft Fax. MAPI helps Microsoft Exchange Clients manage stored messages and define the purpose and content of messages.

The Microsoft Exchange Client can communicate with any electronic mail system or messaging application that has a MAPI service provider, which is similar to a personal gateway. It specifies all the connection and addressing settings needed to communicate with a mail server on one end and with the Microsoft Exchange Client on the other end. The Microsoft Exchange Client includes an OLE-compatible rich-text editor used for reading and composing messages; it supports the use of bullets, multiple font sizes and colors, and text alignments in messages.

The Microsoft Exchange Server Software Development Kit (SDK) provides a rich collection of tools for designing and developing high-performance, custom information-sharing and messaging-service applications.

Using the Microsoft Exchange Server SDK, you can:

  • Extend Microsoft Exchange Server using the SDK sample applications.
  • Build client and server applications customized for your environment using the sample applications.
  • Develop client and Microsoft Exchange Server Administrator program extensions for Microsoft Exchange Server.
  • Develop stand-alone client and server applications for Microsoft Exchange Server.

The following topics present an overview of the Microsoft Exchange Server SDK and its documentation, and highlight important development issues in creating effective Microsoft Exchange Server applications.


System Requirements and Recommendations for Microsoft Exchange Server

To develop applications for Microsoft® Exchange Server, the following hardware is recommended:

  • Intel 80486/25 or higher processor; Intel Pentium or Pentium Pro processor; RISC-based microprocessors such as MIPS R4000 and Digital Alpha AXP; or PowerPC
  • Super VGA (800 x 600) 256-color display
  • At least 50 MB space on the partition containing Microsoft® Windows NT® Server files for the SDK, plus the space necessary for the Microsoft® Visual C++® version 4.0 development system, Windows NT Server, and Microsoft Exchange Server components required by your development
  • CD-ROM drive
  • 32 MB RAM or more
  • Network adapter card

In addition to the recommended hardware, the following software is required:

  • Microsoft Windows NT version 3.51 or later, with Service Pack 4
  • Microsoft Exchange Server must be running on the domain
  • Microsoft Platform SDK
  • Microsoft Exchange Client
  • Microsoft® BackOffice™ Software Development Kit (SDK)
  • Microsoft Visual C++ version 4.0; earlier versions are not supported

Sample applications may require the Microsoft Exchange Server Administrator program to be running on the development computer.


Using Microsoft Exchange Server as a Development Platform

Applications designed using Microsoft® Exchange Server can take many forms, depending on developer requirements and design objectives. Typically, there are three categories of Microsoft Exchange Server applications:

  • Client applications, which use the services of a server running Microsoft Exchange Server, but reside exclusively at the user's location.
  • Server applications, which interact with services such as the information store and directory to provide services to users, but are not associated with any user.
  • Combined client/server applications, which include a client component associated with one or more users and a server component that is a service.

The following topics present an overview of the development issues necessary to build Microsoft Exchange Server applications.


Developing Client Applications

Development of client applications within the Microsoft Exchange Server environment is accomplished by either extending the Microsoft Exchange Client, or by creating stand-alone client applications.

You can build Microsoft Exchange Server client extensions that add functionality to the Viewer, such as new pull-down menus or function keys.

Other possibilities for extension development include:

  • Custom event handling to launch applications.
  • Subclassing the Viewer window and adding an additional pane.
  • Replacing the advanced search criteria window with a custom search criteria window.

You can also develop your own client application. Most client applications interact with Microsoft Exchange Server by retrieving data from the information store, placing information in a public folder, or manipulating messages to be sent or posted. Your application can perform actions similar to those of the existing Microsoft Exchange Client, or it can supply new functionality.

An example of a unique client application is the Microsoft® Schedule+ client that is provided with Microsoft Exchange Server, as well as with the Microsoft® Windows NT® and Windows® 95 operating systems. Schedule+ enables users to schedule group meetings, manage their daily appointment schedules, track projects and tasks, maintain lists of contacts, and perform many other time- and resource-management tasks. The characteristics of the Schedule+ client are founded on the functionality and features of Automation and can be customized using the Schedule+ Automation interface.


Developing Server Applications

Server applications can be developed either as extensions to the Microsoft Exchange Server Administrator program or as stand-alone applications. The Administrator program performs basic operations such as creating mailboxes, managing basic Microsoft Exchange Server components, and managing directory objects. You can extend the Administrator program by adding custom property pages, creating new data fields for a directory object, and adding application-specific extension data.

Stand-alone server applications for Microsoft Exchange Server interact with user services such as the information store and the directory. Server application components can reside on a server running Microsoft Exchange Server, or on any computer running Windows NT Server, even if that system is not running Microsoft Exchange Server. Most stand-alone server applications are either mailbox agents or gateways. Mailbox agents are server applications that are accessed through a mailbox on a server. Gateways are interfaces with other mail systems.


Developing Client/Server Applications

Some applications may require both a client and a service component. Although it is possible for client applications to communicate directly with services using mechanisms such as the Microsoft remote procedure call (RPC) protocol, client application and server application components in the Microsoft Exchange Server environment do not often directly connect in this manner. Instead, client applications and services interact through messages that are sent to recipient objects in the information store. When developing an application with both a client application and a server application component, you must decide how to correctly divide the functionality between the client and server components to optimize the system's overall performance.


The Architecture of Microsoft Exchange Server

Microsoft® Exchange Server is based on a client/server architecture. While Microsoft Exchange Server systems can have many different physical configurations, a typical installation will have some components located on a computer running Microsoft Exchange Server, others located on a computer running the Microsoft Exchange Client, and possibly others located on another computer running a server application of Microsoft Exchange Server.

Before deciding on the design of your client or server application, it is important to understand the basic categories of Microsoft Exchange Server architecture. These categories are:

  • Microsoft Exchange Client components
  • Microsoft Exchange Server components
  • Directory
  • Information store
  • Gateways
  • Messaging

For detailed information about Microsoft Exchange Server architecture, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Microsoft Exchange Client Components

A client can reside on the same computer as the Microsoft Exchange Server, or it can reside exclusively on the user's workstation. Client applications, designed by users to expand the capabilities of Microsoft Exchange Server, employ Microsoft Exchange Server services, but offer no services of their own. A client interacts with Microsoft Exchange Server through MAPI. The significant components of Microsoft Exchange Client are the Microsoft Exchange Client, the Microsoft Exchange Client extensions, the client application, and MAPI.

The following diagram shows a typical arrangement of Microsoft Exchange Client components on a user's workstation.

For detailed information about Microsoft Exchange Client components, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Microsoft Exchange Server Components

Server components providing services for Microsoft Exchange Server often reside on a dedicated computer. The significant components of a server running Microsoft Exchange Server are the directory, information store, and gateways. The following diagram represents the interaction among these components.

Server applications developed for Microsoft Exchange Server interact with components such as the information store and the directory, similarly to the server service for Microsoft Exchange Server, and offer custom services to clients. Server applications can function independently of clients, or they can include a client component. Also, server applications, like client applications, communicate with Microsoft Exchange Server through MAPI.


Directory

Applications use directory objects to find and gain access to services, mailboxes, recipients, public folders, and other objects that are addressable within the messaging system. Applications you develop must frequently access the directory to look up information about objects in a Microsoft Exchange Server system.

The directory consists of two components: the directory database and the directory service agent. The directory database stores the information provided by the directory. The directory service agent manipulates information in the directory database and handles directory requests from applications and services.

Microsoft Exchange Server directory functionality is implemented through two separate, but related structures:

  • The directory information tree (DIT), which describes how objects in the directory are logically configured to represent an organization into which Microsoft Exchange Server is installed.
  • The directory schema, which defines the directory's object classes and their inheritance structures.

In Microsoft Exchange Server, directory objects defined by other messaging systems (such as SMTP and X.400) are referred to as external objects and are accessible from within the Microsoft Exchange Server messaging environment.

Applications access directory information through two mechanisms:

  • Microsoft Exchange Server directory access functions, which are most often used for setting up and maintaining applications and by server applications where appropriate.
  • MAPI address book functions from both server- and client-based applications. MAPI address book functions can also be used to write information to the directory and to create objects of selected classes in the directory.

Subject to a small amount of latency time needed for the directory replication process, every Microsoft Exchange Server directory within an organization has the same directory objects. Administrators and applications can frequently add, delete, and modify directory objects, and changes to one copy of the directory will be periodically propagated to all other copies of the directory on all other servers. The directory exchange agent synchronizes directory contents with directories on other servers.

Maintaining synchronization on directories that reside in different messaging systems is an important administration and design issue. No periodic synchronization mechanism for a specific subset of directory objects is provided. However, you can design a utility that runs as a service of Windows NT Server.

For detailed information about the directory, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Information Store

Microsoft Exchange Server includes the following four information stores, all of which are implementations of MAPI message stores:

  • Public information store
  • Private information store
  • Personal folder store
  • Offline information store

The public information store contains public folders and messages that can be shared among multiple users and applications. A single public store is shared by all users within a Microsoft Exchange Server organization, even if multiple servers are used. The public information store is accessed similarly to any other MAPI store, using MAPI methods to perform most functions. However, some parameters to these methods differ from those used in other MAPI providers.

The private information store consists of mailboxes that can belong to users or to applications. Mailboxes reside at the server running Microsoft Exchange Server. With the Microsoft Exchange Client, each newly-created mailbox has four visible default folders (Deleted Items, Inbox, Outbox, and Sent Items) and several other folders that are not visible (used for storing information).

The personal folder store is part of the Microsoft Exchange Client, resides at the client computer, and is used to store items that are owned by individuals and not shared by multiple users. Personal folders can also be designated as the delivery location for mail if a user wants to store e-mail messages locally. Mail delivered to personal folders is still funneled through the mailbox on the server running Microsoft Exchange Server, but is stored wherever the personal folders are located.

The offline information store contains synchronized copies of selected folders and is created only when the user synchronizes these folders for offline access using local replication.

The message transfer agent (MTA) provides the addressing and routing information for sending messages and distributing information through the system. The MTA is the engine for routing and transferring data between Microsoft Exchange Server systems or between a Microsoft Exchange Server system and a foreign system. Each MTA is associated with one information store. The Microsoft Exchange Server MTA conforms to the 1988 X.400 Specification.

For detailed information about information stores, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Gateways

Gateways are interfaces that connect electronic messaging systems with different message and address formats. In their simplest form, they receive mail messages, translate them from one messaging system's format to another, map the address between the two systems, and then deliver the translated messages. A gateway can translate messages between mail systems within a single organization, or between an organization and an outside mail system.

For detailed information about gateways, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Messaging

When Microsoft Exchange Server sends a message, it relies on the MAPI subsystem to direct client requests to one or more transport-service providers.

MAPI defines three types of transport-service providers:

  • Message store providers, which supply message storage, organization, and retrieval facilities for a messaging system.
  • Address book providers, which supply message addressing and distribution list facilities to the messaging client.
  • Messaging transport providers, which move messages between messaging clients.

When a message is sent from a client application, MAPI.DLL responds to the common mail call (CMC) or MAPI call. MAPI then routes the messages to the appropriate message store and address book service provider.

The Microsoft Exchange Server information store offers more functionality than many other MAPI message stores. For example, replication services are part of the Microsoft Exchange Server information store and add new functionality that is then available to MAPI applications. The replicated storage model allows the Microsoft Exchange Server information store to distribute information within an organization or beyond its boundaries without requiring users to know the location of the folders containing the information.

For detailed information about messaging within Microsoft Exchange Server and about MAPI, see the "Database and Messaging Services" section of the Microsoft Platform SDK.


Building Client/Server Applications

This section introduces the tools and programming issues you will need to understand before building client/server applications for Microsoft® Exchange Server. Areas of importance include the Microsoft Exchange Server development environment, debugging, application design, server functionality, and application installation.


The Microsoft Exchange Server Development Environment

The Microsoft Exchange Server system is a MAPI service provider built on the Microsoft® Windows NT® Server platform employing the Active Messaging Library. You can use Microsoft® Visual C++® or Visual Basic® to develop Microsoft Exchange Server applications. You can also use the interfaces included with Microsoft Exchange Server and the Microsoft Exchange Server SDK. Choosing the most appropriate tools depends on the application you plan to develop and the environment in which it will run.

The typical Microsoft Exchange Server SDK development environment includes the following components:

  • Microsoft Windows NT Server version 3.51 or later as a base platform.
  • Visual C++ version 4.0 or later (earlier versions are incompatible with the Microsoft Exchange Server SDK).
  • Microsoft Exchange Client.
  • Microsoft Exchange Server. For many applications, you must install the entire Microsoft Exchange Server product. Some applications require only the Administrator program.

After installing the above components, you can install the SDK itself. Also, you must ensure that the proper changes have been made to the system environment variables. Specific information regarding the correct setting of registry and environmental variables can be found in the Microsoft Exchange portion of the Microsoft BackOffice Resource Kit. To guide you through the development process, as well as illustrate the features of Microsoft Exchange Server, Microsoft has provided several sample applications in the Microsoft Exchange Server SDK.

For more information about the tools necessary for application development for Microsoft Exchange Server, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Debugging Applications

Selecting the appropriate debugging method is an important part of the development process. For example, the simplest way to begin debugging your server application is to run it as a Windows NT Server console application so you can step through your code from the first instruction. Once your application is running smoothly, you can attach the debugger to the running process. To debug initialization routines, you can use the IMAGE PATH environment variable to run the server under the debugger.

MAPI and Microsoft Exchange Server contain several mechanisms for detecting and preventing errors. These include the EDKDEBUG library, parameter checking, and checking error returns. MAPI provides a complete debugging version that you can install and use. Some components require extra handling during the debugging process. These include proxy generation DLLs and Administrator extension DLLs.

The Microsoft Exchange Server SDK provides several debugging tools:

  • The Raw Properties screen, which allows you to view and change properties during development.
  • The Track Message utility, which determines the origin and destination of messages as your application processes them.
  • The Queue Viewer sample application, which tests message-handling applications.

The Microsoft Platform SDK includes an additional debugging tool for MAPI, message store viewer, which provides detailed information on any object in the information store.

For more information about application debugging in the Microsoft Exchange Server environment, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Designing Client/Server Applications

This section presents an overview of the types of Microsoft Exchange Server applications you can build, as well as important programming issues you should consider during application development.


Using Client Extensions

Microsoft Exchange Server client extensions allow you to add functionality to the user interface with limited development effort.

Extending the Microsoft Exchange Client usually involves adding functionality to the Viewer, the main window in the Microsoft Exchange Client. The Viewer is the user's primary interface, where users access, organize, and exchange information. The Viewer groups all kinds of information in one place, including such diverse objects as e-mail messages, word-processing documents, voice mail, faxes, spreadsheets, presentation graphics, meeting requests, and customer contact reports. The toolbar is the interface for tasks such as printing, creating a new message, deleting an item, or viewing the address book.

Using client extensions to expose application-specific functionality is usually appropriate when one or more of the following conditions is satisfied:

  • The application adds to the core capabilities of Microsoft Exchange Server, rather than uses Microsoft Exchange Server as a mechanism to deliver completely separate functionality.
  • The new features are used in the context of a particular message or folder in the Microsoft Exchange Server information store.

Typical client extensions include custom menu commands, customized event handling, supplied advanced search criteria, and the addition of a new pane to the Viewer window.

For more information about developing client extensions, see "Extending the Microsoft Exchange Client" in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Using Client Applications

A client application is a program that runs on a user's computer and is controlled through a user interface. Most client applications interact with Microsoft Exchange Server by retrieving data from the information store, placing information in a public folder, or manipulating messages to be sent or posted. A third-party client application can perform actions similar to those of the existing Microsoft Exchange Client applications, or it can supply new functionality.

It is not necessary for a client application to be accompanied by a server application. Furthermore, Microsoft Exchange Server can support client applications that run independently—whether or not a Microsoft Exchange Client is running at the same time. You take advantage of this support by setting up your client application to operate directly through MAPI and to connect its logon process to an existing MAPI-compliant Microsoft Exchange Server application session. The application can then interact with information in the Microsoft Exchange Server information store and manipulate information stored and distributed by Microsoft Exchange Server.

Developing a separate client application is appropriate when:

  • Your application presents users with a different user interface than that of a Microsoft Exchange Client, but provides access to Microsoft Exchange Server information.
  • Your application presents Microsoft Exchange Server information in a way different from what users normally encounter. Microsoft Schedule+ is a good example of this type of client application. Scheduling information is stored and distributed through replication by Microsoft Exchange Server, but the context in which it is presented differs from other Microsoft Exchange Clients.

A client application uses profiles to log on to MAPI. However, unlike a server application that creates its own profile, a client application can connect on a user's existing profile, making its startup cleaner and faster. You can also set up your client application to log on and off using its own MAPI session instead of connecting to an existing session (such as a Microsoft Exchange Client session).

For more information about developing client applications and application design, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Using Server Applications

Server applications extend the basic functionality of Microsoft Exchange Server. They can be used to provide a broad range of services, from mail gateways and voice mail to document management, content indexing, and electronic newspapers.

Similar to developing a Microsoft Exchange Client application, you can develop server applications in two ways: as extensions to the Administrator program, or as stand-alone applications.

Administrator Program Extensions

The primary duties of a Microsoft Exchange Server administrator are basic operations such as creating mailboxes, managing the basic components of Microsoft Exchange Server, and managing directory objects. A server application's directory object makes the application visible to the Microsoft Exchange Server Administrator program. Through the Administrator program, administrators manage an application's directory attributes by using its object's property sheet. Property sheets are composed of one or more property pages. You can extend the Administrator program to include custom property pages, and you can add custom property pages by creating Administrator extension DLLs.

You can also create new data fields for a directory object, control these new fields through custom property pages, and manage this application-specific extension data. These custom property pages can be used by administrators to view other data accessible on a Microsoft Exchange Server system, such as data in the information store.

Several sample applications included with the Microsoft Platform SDK illustrate how you can create Administrator extension DLLs that extend the abilities of the Administrator program, including the Queue Viewer (QUEVIEW), the Extension Data Viewer (EXTDATVW), the Sample Mailbox Agent (SMBAGENT), and the Sample Gateway. Extending the Administrator program offers the following centralized administration capabilities:

  • A single managing program. The Administrator program can be used to control a wide range of applications from many different vendors.
  • Availability of advanced features. Advanced features of the Administrator program, such as remote administration, are available to all applications.
  • Replication. The Microsoft Exchange Server directory is replicated across an entire organization. Objects stored in the directory benefit from this automatic replication mechanism.
  • Available user interface. The Administrator program provides a user interface, so you don't need to write one and users and administrators don't need to learn an additional user interface.

For more information about developing Administrator program extensions, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.

Server Applications

A server application can be either a mailbox agent, a gateway, or an add-in application, and should be implemented as a service of Windows NT Server. This means that the application is event-driven and can be controlled through the Service Control Manager of Windows NT Server. It can function as an independent process before users log on, and it has an instance name to be used when logging on to MAPI.

When an application runs as a service of Windows NT Server, the Service Control Manager is usually called to find its main function when it starts, to provide its messaging interface, and to tear it down gracefully when it ends. The interface with the Service Control Manager can be handled in two ways: either by using Windows NT Server functions, or by using the Winwrap library functions. The Winwrap library, developed for Microsoft Exchange Server, usually provides a more convenient way to handle the interface between a server application and the Windows NT Service Control Manager.

A server application communicates with Microsoft Exchange Server components through MAPI. This communication includes actions such as using the address book, accessing information stores (including public folders), and transferring messages. Special functions are included with the Microsoft Exchange Server SDK that were developed for communication between server applications and Microsoft Exchange Server. Some of these functions extend MAPI functionality, some enhance debugging capabilities, and others add completely new functionality.

Most server applications are represented in the Microsoft Exchange Server directory as either Mailbox-Agent or Mailbox-Gateway objects. To provide their services, these server applications must communicate with directory objects and information store objects. Additionally, depending on their functionality, many server applications must communicate with the Administrator program as well as with Administrator extensions. A server application is not required to run on the same computer as Microsoft Exchange Server because most server applications use MAPI, which is a remote procedure call (RPC) interface and can therefore be used over a network connection.

For more information about developing Administrator program extensions, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Optimizing Application Performance

Designing a client or server application for optimum performance is a fundamental development goal. This is particularly true for Microsoft Exchange Server applications where the range between average and excellent performance is quite noticeable.

Recommendations for achieving performance gains include minimizing the number of remote procedure calls (RPCs), using the most efficient MAPI calls, using the MAPI idle engine, inspecting for memory leaks, and using the appropriate data stream (IStream interface or buffered data stream). Other performance recommendations exist as well.

You can also improve the performance of your applications by using the tools supplied by Microsoft Exchange Server and Windows NT Server, which include the Windows NT Performance Monitor and the FERNEL32 DLL. Additionally, the Network Monitor tool helps determine where network bottlenecks are occurring.

For more information about optimizing application performance, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Managing Directory Operations

The Microsoft Exchange Server directory contains information about mailboxes, distribution lists, servers, processes, and applications. It provides a unified, structured view of all users and resources within the Microsoft Exchange Server system.

All objects in the Microsoft Exchange Server directory are addressable. You can manage the directory using Microsoft Exchange Server directory access functions or the MAPI IAddrBook interface.

Directory access functions are specific to Microsoft Exchange Server. Applications that use Microsoft Exchange Server directory access functions run on Windows NT Server computers on which the Microsoft Exchange Server Administrator program is installed. These functions are not available to Microsoft Windows 95 clients. You can use directory access functions to create, manipulate, delete, export, and import directory objects.

Using directory access functions, you can write programs that export directory objects into an export file or into a data structure. A typical use for an export file is synchronizing directories between a Microsoft Exchange Server site and a directory of a different type (such as a foreign mail system or a database). You can also use these functions to move user information from Windows NT Server and Novell NetWare accounts into the Microsoft Exchange Server directory.

The directory access functions combine and automate several maintenance tasks. For example, with a single call, you can create a mailbox object, create and associate a Windows NT Server account and associate the mailbox object to it, add proxy addresses, assign user privileges, add the mailbox to distribution lists, and set its other attributes.

The Microsoft Exchange Server address book provider offers access to directory objects through the MAPI address book interface. Using MAPI, you can create and delete directory objects, as well as view and change their attributes. To manipulate directory objects through the Microsoft Exchange Server address book provider, you must generate MAPI entry identifiers for the objects.

The Microsoft Exchange Server directory can share its object addressing and configuration information with other mail systems. Several methods are available to transfer directory information between Microsoft Exchange Server organizations and foreign systems.

For more information about directory operations, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Working with the Information Store

A Microsoft Exchange Server information store contains messages, forms, documents, and other information created by users and applications. It provides each user with a server-based mailbox and stores public folder contents.

MAPI functions and methods are used to work with Microsoft Exchange Server information stores. The important development tasks that are performed when working with information stores include locating and opening an information store, opening a public information store, and determining the type of information store.

As a developer, you should become familiar with the information store's structure and interface as well as with its relationship to other Microsoft Exchange Server components. Some examples of important development issues are:

  • Managing folders. You can customize and manipulate public, private, and personal folders by programming with MAPI and using features such as ACLs, rules, and folder replication.
  • Handling messages. Messages are MAPI objects that are transmitted from one client application to another through the MAPI spooler and service providers by way of a messaging system. Every message supports many properties; which describe the message, its contents, transmission options, and recipients.
  • Granting privileged access. Applications may need to dynamically access multiple mailboxes. These applications, called privileged services, must be granted special privileges by a Microsoft Exchange Server administrator.
  • Backing up and restoring data. Functions for backing up and restoring data in the Microsoft Exchange Server directory and information store are provided in the Microsoft Exchange Server SDK. These functions perform backups online, which means that there is no need to stop the directory or information store service to back up directory or information store data.
  • Providing event notification. Event notification is the communication of information between two MAPI objects. One object registers an interest in learning of a change or error, called an event, that may take place in another object. After the event occurs, the first object is informed or notified.

For more information about information store operations, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Using Forms in Applications

With Microsoft Exchange Server, you can develop forms-based applications using MAPI forms interfaces. These interfaces give you the ability to define custom forms, install them in forms libraries, and supply them to users of Microsoft Exchange Server. You can also develop forms with the Microsoft Exchange Forms Designer, which in turn calls the MAPI forms interfaces. Any MAPI-compliant forms application can run in the Microsoft Exchange Server environment and use functionality such as the organization form library, folder forms libraries, and conflict-resolution capability.


Providing Setup Programs

You may need to provide a setup program for your server application (mailbox agent or gateway) or client application that includes a server component. This setup program will allow users to install, configure, and remove your application within the Microsoft Exchange Server environment.

One function of the setup program is to copy all necessary files from floppy disks or CD to the server's hard disk. Depending on the application's level of interaction with Microsoft Exchange Server system components, the setup program must also ensure that the application is recognized by the components and can communicate with them.

The amount of interaction between the server application and Microsoft Exchange Server depends on the application's design. Server applications can be developed that depend very little on Microsoft Exchange Server. However, this independence from Microsoft Exchange Server and Microsoft Windows NT Server has its drawbacks. For example, if you design your application to use the Windows NT registry, you can use the utility functions provided with the Microsoft Exchange Server SDK to more easily manage the application's configuration information—including both standard data and extension data.

Important tasks your setup program may need to perform include:

  • Querying and collecting system installation requirements from the administrator.
  • Installing the application as a service of Windows NT Server by writing its configuration information to the Windows NT registry.
  • Installing an Administrator extension object for the correct Administrator extension DLL (if one is required).
  • Copying the required files for Administrator extensions or address types.
  • Creating the application object in the Microsoft Exchange Server directory.
  • Setting up performance monitoring for your application.

The Microsoft Exchange Server SDK provides the sample setup programs GWSETUP for installing a gateway and MBSETUP for installing a mailbox agent. For more information about setup programs for Microsoft Exchange Server, see the Microsoft Exchange Server documentation in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Programming Gateways

Microsoft® Exchange Server gateways provide the interface between mail systems founded on different message and address formats. Gateways can be implemented to translate messages between two mail systems residing within a Microsoft Exchange Server organization, or between an organization's mail system and an external mail system.


Gateway Overview

In Microsoft Exchange Server, a gateway is an interface connecting two or more electronic messaging systems that, typically, have different message and address formats. In general, the function of a gateway consists of several actions:

  • Receipt of a mail message. When a user sends a message, Microsoft Exchange Server determines whether the message can be delivered to that recipient by Microsoft Exchange Server or must be transferred by a gateway. If a recipient is on a foreign mail system, the message is assigned to the appropriate gateway. The gateway then receives the message from its MAPI folder MTS-OUT.
  • Message translation. The translation of messages between different mail systems is accomplished within Microsoft Exchange Server by a conversion engine. One message characteristic is the message class, a description providing information about the set of properties defined for the message. Upon receipt of a message, the gateway examines the message class and determines the appropriate conversion engine to invoke.
  • Delivery of the translated message. After translation of the message, the gateway examines the contents of the Message Transfer Envelope to determine the delivery information for the message. The message is then delivered based on the contents of the recipient list.


Gateway Development Considerations

Development issues for gateway applications fall into several distinct categories: addressing, message transfer and translation, report generation, backboning, administrative functions, and gateway setup programs.

The following topics highlight these important issues in creating gateway applications using the Microsoft Exchange Server SDK.


Issues About Addressing in Gateway Applications

Addressing is an important element of a Microsoft Exchange Server gateway because the gateway must accurately address mail to users in both the Microsoft Exchange Server system and the foreign system it serves. The two primary addressing issues to consider are determining proxy addresses and mapping addresses.

Most foreign systems use an address type and format different from Microsoft Exchange Server. A proxy address is the address by which a Microsoft Exchange Server user is recognized in a foreign mail system. Each Microsoft Exchange Server user can have several proxy addresses—one or more for each foreign system to which Microsoft Exchange Server is connected by a gateway. Also, users can have a primary proxy address, the primary address for a user sending mail to a foreign system, and a secondary proxy address, the address used when receiving mail from the foreign system.

For messages going out from Microsoft Exchange Server, your gateway must convert all addresses to a form that is compatible with the foreign system. For messages coming into Microsoft Exchange Server, it must change all addresses to a form compatible with MAPI and the underlying Microsoft Exchange Server system.


Transferring and Translating Messages

A gateway's primary task is to transfer messages. Microsoft Exchange Server facilitates this function by wrapping the message in a Message Transfer Envelope (MTE) that provides a list of recipients to whom the gateway must deliver the message. Your gateway must process MTE information and deliver the attached messages, and also transfer several types of reports that inform message originators and recipients about message status.

A gateway must translate messages and transfer their contents between a MAPI mail system format and a foreign system format with minimal loss of information. To accomplish this, each message is translated by a program called a conversion. For each message, the conversion engine selects the correct conversion based on the message class and the gateway.


Generating Reports

Microsoft Exchange Server gateways generate reports to inform message originators of the success or failure of message delivery and receipt. All Microsoft Exchange Server reports should conform to the minimum required content and semantics of the X.400 Specification. Content and functionality beyond that required by the X.400 Specification are optional. Microsoft Exchange Server currently supports four classes of reports: delivery status reports, nondelivery reports, receipt notifications, and nonreceipt notifications.


About Backboning

Backboning is the process of transmitting messages between two similar messaging systems using an intermediate system of a different type. The goal of backboning is to send messages between Microsoft Exchange Server sites in different organizations as easily as you do between two users at the same site. Because of the necessity of integrating different messaging systems, backboning is an important feature that should be offered by all Microsoft Exchange Server gateway applications.


Administrative Functions

Microsoft Exchange Server administrative functions are designed to allow you to administer, monitor, and optimize a gateway's performance using minimal system resources. The three administrative functions your gateway can perform are:

  • Error handling. Gateways can generate or store detailed error information.
  • Message tracking. Event tracking traces the progress of messages traveling through the gateway to Microsoft Exchange Server or to the foreign mail system.
  • Performance monitoring. Gateways can log performance statistics to the Windows NT Performance Monitor.

Microsoft also provides you with the ability to configure gateways. Gateway setup programs allow users to install, configure, and remove gateways within the Microsoft Exchange Server environment.

For more information about gateway programming, see "Gateway Programmer's Reference" in the "Database and Messaging Services" section of the Microsoft Platform SDK.


Developing Microsoft SQL Server Applications

This section provides a brief overview of some of the important topics to consider when developing applications that interact with Microsoft® SQL Server. For additional information about Microsoft SQL Server functionality, or about development specifications and guidelines, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Introduction to Microsoft SQL Server

Microsoft® SQL Server is a powerful Structured Query Language (SQL) database server. With local area network (LAN) software, SQL Server allows clients running the Microsoft® Windows NT®, Windows® 3.x, Windows 95, or MS-DOS® operating systems to access its services. Developers can write applications for SQL Server by programming with the Microsoft Open Database Connectivity (ODBC) call-level application programming interface (API). ODBC enables Windows-based, Windows NT-based, and Windows 95-based applications to access multiple data sources, including a wide range of relational databases such as SQL Server and local indexed sequential access method (ISAM) data. SQL Server also supports the proprietary Microsoft DB-Library for C and Microsoft DB-Library for Visual Basic APIs. In most cases, ODBC and DB-Library are equally useful for developing SQL Server client applications, with the following distinctions. ODBC enables applications to access more data sources. DB-Library provides support for MS-DOS, and some specialized support for SQL Server, such as bulk copy.

Microsoft Open Data Services (ODS) is a server-based API that developers can use to create effective server applications. Applications created with ODS can interact with SQL Server database clients and servers, and with any other elements of a network environment that the developer defines.

Additionally, developers can use Transact-SQL to work with SQL Server data. Transact-SQL provides statements for creating and manipulating database objects, and for inserting, updating, and selecting data.

The following sections present an overview of the Microsoft SQL Server programming tools and highlight development issues that are important to create effective SQL Server applications.


New Features in Microsoft SQL Server Version 6.5

Microsoft® SQL Server version 6.5 builds on the foundation of performance, reliability, and scalability provided by SQL Server version 6.0. SQL Server 6.5 enhances that foundation as well as extends it into new areas such as the World Wide Web. New features in SQL Server 6.5 can be grouped into several categories:

  • Expanded tool functionality
  • Enhanced SQL Server architecture
  • Improved data processing and verification


Expanded Tool Functionality

Microsoft SQL Server version 6.5 provides enhancements for administration tools such as SQL Enterprise Manager. Enhancements to SQL Enterprise Manager include a Database Maintenance Plan Wizard, a built-in database transfer management interface for copying objects between databases, support for enhancements such as table dump and load and point-in-time recovery, enhanced menu options, and graph controls. Additionally, external applications can be added to the Enterprise Manager's menu and executed.

SQL Server 6.5 also provides new tools, including:

  • SQLTrace, a graphical utility for monitoring and recording database activity.
  • SQL Server Web Assistant for HTML publishing using SQL Server data.
  • Microsoft Query for querying tables and viewing data.
  • Microsoft Distributed Transaction Coordinator for administering distributed transactions.


Enhanced Microsoft SQL Server Architecture

Microsoft SQL Server version 6.5 has been enhanced to meet the American National Standards Institute (ANSI) SQL-92 standards and has been certified as compliant with Federal Information Processing Standards (FIPS 127-2) established by the National Institute of Standards and Technology (NIST).

SQL Server 6.5 includes new SQL Distributed Management Objects (SQL-DMO) objects — Transfer, BulkCopy, ServerGroup, and RegisteredServer — and enhances the functionality of existing SQL-DMO objects.

Some SQL-DMO objects now support ConnectionPoint events, which allow you to write Component Object Model (COM) objects that are notified by SQL-DMO objects when certain events occur. SQL Server 6.5 includes new OLE Automation stored procedure support, which allows you to write an extended stored procedure with Microsoft® Visual Basic®.

The ODBC SQL Server Driver in SQL Server 6.5 now includes:

  • Support for enlisting in MS DTC transactions using a new driver-specific connection option.
  • Support for driver-specific column attributes (SQLColAttributes), similar to certain DB-Library functions.
  • Logging of performance data and long-running queries.
  • The ability to use static server-side cursors on ODBC catalog functions and to call ODBC catalog functions inside a transaction.
  • Support for other SQL Server 6.5 enhancements.

The backup and recovery capabilities managed by SQL Enterprise Manager have been enhanced, which means that individual tables can be backed up and restored; transaction logs can be recovered through a specified date and time; a transaction history is maintained about backups from a particular database; and greater options are now provided in the Database Backup/Restore dialog box. Enhancements have been made to the SQL Server replication capabilities, especially to text and image data types. Also, SQL Server 6.5 allows you to tune performance of systems containing four or more processors by assigning thread execution to specific processors, thus minimizing the overhead incurred by threads switching between multiple processors.


Improved Data Processing and Verification

Microsoft SQL Server version 6.5 enhances present cursor functionality by supporting updates on tables that do not have a unique index and cursors that automatically close when a transaction commits. SQL Server 6.5 allows Data Definition Language statements (for example, CREATE and DROP statements) within a transaction. The DBCC DBREINDEX statement allows one or more indexes for a table to be rebuilt.

Many improvements in SQL Server 6.5 are designed to ease the development process and provide you with greater programming options. Some of these improvements are:

  • A 32-bit DB-Library for Visual Basic OLE custom control.
  • Enhancements to DB-Library for C including support for enlisting in MS DTC transactions using the new dbenlisttrans and dbenlistxatrans functions, and the ability to open cursors on stored procedures using dynamic parameters.
  • Additional Open Data Services (ODS) functionality including bound session support by using the new srv_getbindtoken function.
  • Embedded SQL for C functionality including ANSI compatibility.

SQL Server provides support for extended stored procedures, allowing SQL Server to dynamically load and execute a function within a dynamic-link library (DLL) in a manner similar to that of a stored procedure. Actions outside of SQL Server can be triggered, and external information can be returned to SQL Server for manipulation.

SQL Server 6.5 now supports distributed, atomic transactions between two or more SQL Server systems. SQL Server 6.5 also adds new Transact-SQL capabilities such as CUBE and ROLLUP operators, row-level locking during certain transactions, and bound connections.

For a complete description of the enhancements contained in Microsoft SQL Server version 6.5, see the SQL Server documentation.


System Requirements and Recommendations for SQL Server

To develop applications for Microsoft® SQL Server, the following hardware is required:

  • Intel 80486/25 or higher processor; Intel Pentium or Pentium Pro processor; RISC-based microprocessors such as MIPS R4000 and Digital Alpha AXP; or PowerPC
  • At least 60 MB of available disk space
  • CD-ROM drive
  • 16 MB RAM required (32 MB RAM or more is recommended)
  • Network adapter card and software

In addition to the required hardware, the following software is required:

  • Microsoft® Windows NT® version 3.5 or later (Windows NT version 3.51 or later is recommended)
  • Microsoft SQL Server version 6.0 or later
  • Microsoft Platform Software Development Kit (SDK)


Programming with ODBC

Applications using the Open Database Connectivity (ODBC) API can access Microsoft® SQL Server. ODBC is an implementation of database API standards defined by X/Open and the International Standards Organization (ISO). Applications that are coded to the ODBC API can use DBMS-specific drivers to access different databases without being rewritten to use the proprietary API of each DBMS.

Microsoft SQL Server includes an ODBC driver that allows ODBC applications to work with SQL Server data. The performance of ODBC applications using the Microsoft SQL Server ODBC driver is equal to the performance of applications using the older DB-Library API; therefore Microsoft supports ODBC as a native API for Microsoft SQL Server.

ODBC is a fairly low-level API, and several other Microsoft database APIs are built over ODBC. These APIs are either easier to code than ODBC, or offer tighter integration with their development language. Through its ODBC driver, Microsoft SQL Server also supports applications written to these APIs:

  • Microsoft® Visual Basic® Remote Data Objects (RDO)
  • Microsoft Visual Basic Remote Data Controls (RDC)
  • Microsoft® Visual C++® Microsoft Foundation Classes (MFC) Database Classes
  • Microsoft Visual Basic Data Access Objects (DAO)
  • Microsoft Visual C++ DAO Classes

The OLE DB API is similar to ODBC. It allows an application to access data from heterogeneous sources without being rewritten to use the proprietary API of each data source. While ODBC is designed for C applications, OLE DB is designed to be used in C++ applications. ODBC also requires that a data source support at least a minimum set of SQL statements, and therefore is used primarily to access relational and ISAM databases. OLE DB does not force this use of SQL, and therefore supports a wider range of nonrelational data. OLE DB includes an OLE DB ODBC provider that allows OLE DB applications to use existing ODBC drivers. OLE DB applications can use the OLE DB ODBC provider along with the Microsoft SQL Server ODBC driver to access Microsoft SQL Server. The Microsoft Active Data Objects (ADO) API is built on OLE DB in the same manner that DAO and RDO are built on ODBC. Microsoft SQL Server also supports ADO applications using the Microsoft SQL Server ODBC driver.

These APIs offer a rich set of functions you can use to:

  • Open connections to many different data sources.
  • Format queries.
  • Send query batches to the server and retrieve the resulting data.
  • Use scrollable cursors.
  • Execute stored procedures, remote stored procedures, and extended stored procedures.

While the ODBC-based APIs are more portable than DB-Library and offer roughly equal performance, there is no compelling reason to convert existing DB-Library applications. Microsoft recommends that new SQL Server applications, or significant rewrites of DB-Library applications, be written to the ODBC-based APIs rather than the older DB-Library-based APIs. The use of DB-Library-based APIs should be limited to maintaining existing DB-Library applications, or for applications that require the DB-Library bulk copy functions.

The primary database API currently used by Visual C++ applications is the MFC Database Classes. The MFC Database Classes in Visual C++ version 5.0 do not support ODBC 3.0, so applications needing functionality available in ODBC 3.0 must be coded directly to the ODBC 3.0 API.

In Visual Basic version 5.0, the RDO API offers the best performance and functionality when accessing Microsoft SQL Server. RDC is a simpler API that has almost the same performance as RDO when used with Microsoft SQL Server. While the current version of ADO does not support as much functionality as the current RDO, ADO will be the primary Visual Basic database API in the future and will be enhanced to support all the current RDO features. If the current version of ADO supports all the functionality you need, consider using it instead of RDO. The factors to be considered when choosing a Visual Basic Database API are discussed in detail in a whitepaper "Choosing the Right VB5 Data Access Interface" available at http://www.microsoft.com/vbasic/techinfo.

Applications using any of these ODBC-based APIs are subject to the specific behavior of the Microsoft SQL Server ODBC driver. This behavior is discussed in both the SQL Server manuals and the whitepaper "Using ODBC with Microsoft SQL Server" at http://www.microsoft.com/sql/reskit.htm.


Programming with DB-Library

Developers can write applications for Microsoft® SQL Server by programming with DB-Library for C, the C-language version of the communication library for SQL Server, or with DB-Library for Visual Basic, the Microsoft® Visual Basic® version of the communication library for SQL Server.

DB-Library for C is an API that consists of C functions and macros that allow an application to interact with SQL Server. Included are functions that send Transact-SQL statements to SQL Server and functions that process the results of those statements. Additionally, DB-Library for C includes functions for error handling and data conversion.

DB-Library for C offers a rich set of functions you can access to:

  • Open connections.
  • Format queries.
  • Send query batches to the server and retrieve the resulting data.
  • Use scrollable cursors.
  • Bulk-copy data from files or program variables to and from the server.
  • Execute stored procedures or remote stored procedures.

DB-Library for Visual Basic is a set of functions and routines for building front-end applications for the Microsoft® Windows® 3.x and Windows 95 operating systems that interact with Microsoft SQL Server. DB-Library for Visual Basic is built on and is a subset of the SQL Server DB-Library for C.

The following topics present an overview of DB-Library for C and DB-Library for Visual Basic, highlighting issues to consider when using either library to develop applications for SQL Server.


Development Tasks Using DB-Library for C

Different development issues exist for applications created for the Microsoft Windows NT, Windows 95, Windows 3.x, or MS-DOS operating system.

For Windows NT-based and Windows 95-based applications:

  • For the Win32®-based versions of the DB-Library DLL, a separate operating system thread may be spawned for each connection that DB-Library makes with SQL Server.
  • The DB-Library functions for the Microsoft Win32 API are stored in NTWDBLIB.DLL. Net-Libraries for Windows NT and Windows 95 are also implemented as DLLs. In addition, the NTWDBLIB.LIB file is an import library containing function definitions.
  • Several unique features of the Win32 API such as asynchronous query processing, memory management functionality, threads, and re-entrancy should be used in your application for optimum performance.

For Windows 3.x-based applications:

  • The DB-Library functions are stored in MSDBLIB3.DLL. Like Win32-based versions of the Net-Libraries, Windows 3.x Net-Libraries are implemented as DLLs. The MSDBLIB3.LIB file contains the import definitions for your application.
  • You can use several different background processing techniques, such as using the PeekMessage loop instead of the GetMessage loop in the WinMain function, to complete long tasks such as query processing.

For MS-DOS-based applications:

  • You must load a Net-Library terminate-and-stay-resident (TSR) utility to communicate with SQL Server.
  • You can select between two memory models: medium (RMDBLIB.LIB or BMDBLIB.LIB) or large (RLDBLIB.LIB or BLDBLIB.LIB).

Other development issues exist, such as how to compile and link your application, that are specific to the development platform and may need to be examined in detail. If you are porting your application from a Windows 3.x-based or MS-DOS-based environment to a Win32-based environment, certain additional issues may exist.

For detailed information about issues related to application development using DB-Library for C, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Development Tasks Using DB-Library for Visual Basic

In general, developing any application using Visual Basic involves two processes:

  • Providing a user interface that requests information from and conveys information to the person using the application.
  • Supplying the programming code that performs a set of tasks in response to specific user actions.

These two processes are strongly interdependent. When the user of the application initiates an action with a particular screen object, Visual Basic responds by invoking the Basic code contained in whatever event procedure is associated with that screen object. User interaction with SQL Server occurs when the Visual Basic code for an event procedure contains functions and routines from DB-Library for Visual Basic.

Unless your DB-Library for Visual Basic application is very simple, multiple forms should be used to divide your application into logical parts. Applications created using DB-Library for Visual Basic can be large and complex, and can manage several SQL Server processes. Dividing applications into forms and modules that control the various processes makes it easier to maintain and change the applications.

When developing a DB-Library for Visual Basic application, you typically include several required DB-Library for Visual Basic files (VBSQL.VBX or VBSQL.OCX custom control, and VBSQL.BAS files) in your Visual Basic project to provide declarations and functionality.

For detailed information about issues related to application development using DB-Library for Visual Basic, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Using DB-Library Functions

Using DB-Library for C or for Visual Basic, applications can access and manipulate information contained within SQL Server databases. A wealth of functions exist to facilitate this communication and data manipulation. The functionality of the DB-Library falls into the following categories:

  • Core functions perform fundamental operations such as:
    1. Connect to Microsoft SQL Server.
    2. Put Transact-SQL statements into a buffer and send them to SQL Server.
    3. Process any results returned from SQL Server, one statement at a time and one row at a time. You can put the results into program variables, where your application can manipulate them.
    4. Handle DB-Library errors and SQL Server messages.
    5. Disconnect from SQL Server.

    Microsoft SQL Server provides several mechanisms for implementing the preceding steps. You can use SQL Server functions to search for SQL Servers either locally or over the network; to resolve SQL Server names, irrespective of the client platform; to bind the results of SQL Server queries to program variables; and to interpret and effectively handle errors and messages originating from transactions with SQL Server.

  • Cursor functions can be used to exploit and administer cursor functionality (manipulate rows).
  • Stored procedure functions allow you to access stored procedures.
  • Text and image functions can be used to manipulate text and image data types.
  • Browse functions can be used to retrieve information about data, column, and table structures.
  • Bulk copy functions can be used to perform bulk copy operations.

For detailed information about DB-Library for C functions or DB-Library for Visual Basic functions, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Open Data Services

Microsoft Open Data Services (ODS) is a server-based API consisting of C functions and macros used for creating server applications. You can develop two types of server applications using ODS: applications called extended stored procedures that are added directly to Microsoft® SQL Server and accessed through procedure calls to SQL Server, and applications that are initialized as ODS servers and that support user connections and user queries.

Using ODS, you can provide extensions to SQL Server by integrating features from your network environment whenever certain events occur within SQL Server. For example, you can create extension functions that take specific actions based on updates to SQL Server tables, launch programs that are external to SQL Server, or exchange data with an application external to SQL Server. You can even make these functions transparent to SQL Server users.

You can generally make the ODS server application extension functions available as a set of extended stored procedures that you add to SQL Server itself.

You can also provide gateways to non–SQL Server database environments. ODS server applications can connect to relational databases to perform general-purpose data access, or to nonrelational data sources to perform application-specific tasks.

For ODS server applications that provide gateway functions, you might not need to involve a SQL Server database at all; your application can accept connections from multiple local area network (LAN) clients directly, access an external data source on their behalf, and then return responses to the clients.


Building Server Applications Using ODS

Open Data Services (ODS) can provide you with a variety of approaches to building server applications, depending on your development requirements.

Build extended stored procedures. ODS server applications can be integrated as a set of extended stored procedures. This approach can extend SQL Server by way of the Open Data Services API, without providing a separate ODS server application. Instead of running your ODS server application separately and using the ODS Library as a base, you include your application's DLL with the standard SQL Server DLLs and use SQL Server as a base. As a result, each function within your DLL can then be called as if it were a standard SQL Server stored procedure.

Build server applications to extend SQL Server capabilities. ODS server applications designed to extend SQL Server can respond to updates in SQL Server tables, facilitate running external programs, and obtain data from an outside source. For example, this type of server application may be suited to perform functions external to the SQL Server environment, or to capture and reflect current values from the external environment.

Build gateway applications. Gateway applications connect local area network (LAN) clients to external data sources. Gateway applications also can use SQL Server to store or simply deliver data from other systems to LAN clients. Because gateway applications based on ODS can communicate with SQL Server clients, they can take advantage of the client platforms, front-end tools, and network support that SQL Server provides. Gateway applications are particularly useful in mixed database environments because they allow clients to connect to many data sources using a single access library (DB-Library or ODBC) and a single protocol (their LAN transport). This can limit the cost and complexity of connecting to mainframe or minicomputer networks to that of a few powerful servers running gateways.

Build a Windows NT service. You can install an ODS server application as a Windows NT service that responds to Microsoft Windows NT commands such as net start, net stop, and net pause. Windows NT services must use the Win32 API to register with the Service Control Manager.

In addition to selecting the correct approach for developing your server application, you must include specific files, such as header and library files, and follow certain procedures to compile and link the ODS server applications that you develop.

For detailed information about developing ODS server applications, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Programming Open Data Services

Open Data Services (ODS) server applications are event-driven—they respond to a predefined set of events that the ODS Library generates in response to an incoming request or to an error. The programming tasks involved in creating an ODS server application are based on meeting the following requirements:

  • Initializing the ODS server application.
  • Installing a set of error handlers.
  • Installing a set of event handlers that will respond to the main ODS event types by processing incoming requests and returning the results to the user. The main ODS event types are connect, language, and remote stored procedure.

For applications that provide access to a remote data source, the tasks include:

  • Establishing a connection to the data source.
  • Passing user requests.
  • Receiving the results.
  • Returning the results to the user.

ODS also provides an extensive selection of functions and macros, such as those related to data retrieval and language event processing. Moreover, ODS provides three primary data structures to maintain information about the status of the ODS server application and each of the connected client processes.

An ODS server application can take advantage of several memory and thread management features of the Win32® API such as:

  • Threads. ODS uses a Win32 thread management technique called thread pooling to make threads available to active client connections faster in environments that support a large number of users.
  • Windows NT security. ODS provides the capability for a server application to act in the security context of a client that has connected to it. Potential uses include allowing an ODS server application to handle user access entirely through Windows NT facilities, or implementing a unique auditing procedure to track system usage during a client session.

For more information about using the Win32 API in ODS programming, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Network Setup for Open Data Services

Several configuration requirements will affect the network setup of your Open Data Services (ODS) server application including:

  • The type of network you are using.
  • Whether the ODS server application is installed on the same computer as Microsoft SQL Server or on a separate computer.
  • Whether you want to provide clients with direct or remote access to the ODS server application.

When an ODS server application and SQL Server are installed on separate computers on the network, they can use the default SQL Server connection configuration. When an ODS server application and SQL Server are installed together on the same computer, they share the same server name, requiring you to assign an alternate connection configuration to one of them. In addition, any computer that requires direct access to a server application using an alternate connection must be configured to connect to the server by that alternate configuration connection.

ODS can simultaneously accept requests from clients and servers across multiple network protocols. ODS supports multiple network protocols through the use of loadable network drivers, known as Net-Libraries.

SQL Server database servers communicate with ODS server applications by using remote stored procedure calls, the same method used to communicate with other SQL Servers. SQL Server database clients can access an ODS server application remotely, by way of the SQL Server remote stored procedure facility, or directly, by way of a direct connection to the ODS server application.

For some custom applications, clients can access SQL Server indirectly by way of ODS. The ODS server application implements a pass-through server function that directs client requests to SQL Server.

For detailed information about network setup of your ODS, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


SQL Distributed Management Objects

SQL Distributed Management Objects (SQL-DMO) is a set of 32-bit Component Object Model (COM) objects for the Microsoft® Windows® 95 and Windows NT® operating systems. The SQL-DMO object model includes objects, properties, methods, and collections that are used to write programs that can administer multiple SQL Servers distributed across a network. SQL-DMO objects are Automation compatible and can range from simple Microsoft® Visual Basic® scripts to complex Microsoft® Visual C++® applications.


SQL-DMO Environment Setup

The first step to programming with SQL-DMO objects is to include the appropriate type library or header files in your project. To give Microsoft Visual Basic access to the SQL-DMO object definitions, you should include the SQL-DMO type library in your Visual Basic project or module. You must include the type library if you want to declare a Visual Basic object variable as a SQL-DMO object type, but not if you want to declare a Visual Basic object variable as a generic Object type.

In a Microsoft Visual C++ environment, the SQL-DMO objects include both ANSI and Unicode custom interfaces. The ANSI custom interfaces and ANSI SQLOLE_BSTR strings are used by default. To use the Unicode custom interfaces and Unicode SQLOLE_BSTR strings, you must define UNICODE and _UNICODE before including all the header files. To give your Visual C++ program access to the SQL-DMO object definitions, you must include the SQLOLEID.H and SQLOLE.H files, in addition to the Windows and OLE header files. If you are using Visual Basic or Visual C++, there are other requirements and steps as well.

For more information about setting up your SQL-DMO programming environment, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Using SQL-DMO Objects

The core of SQL-DMO is the SQLServer object. For each SQL Server you want to connect to, you create an empty SQLServer object and connect it to a running SQL Server. There are three methods using Microsoft Visual Basic to create SQL-DMO objects (including SQL Server objects). There is only one method to create a SQL-DMO object in Microsoft Visual C++.

After creating a new, empty SQLServer object, you connect that object to a running SQL Server using the Connect method of the SQLServer object. You pass SQL Server name, login identifier, and password parameters to the Connect method. When the Connect method is successful, the SQLServer object is filled with information about the connected SQL Server. The SQLServer object and all objects "under" the SQLServer object (in the SQL-DMO object hierarchy) are now valid and available for use. This availability includes all SQLServer properties (including object properties), all supported SQLServer methods, all SQLServer collections, and all objects "under" SQLServer. SQL-DMO also adds the connected SQLServer object to the application's SQLServer collection.

For more information about using SQL-DMO objects, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Transact-SQL

Transact-SQL is an enhanced version of Structured Query Language (SQL) used to perform transactions and operations with relational database systems. Originally developed by IBM, SQL has been adapted for many relational database management systems (DBMSs) and has been approved as the official relational query language standard by the American National Standards Institute (ANSI). Transact-SQL is compliant with many ANSI SQL standards and also provides important additional capabilities and functions to assist you in creating efficient Microsoft SQL Server applications.

With Transact-SQL, you can retrieve data from a database, create databases and database objects, add data, modify existing data, and perform other complex functions. You can also change the server configuration, modify database or session settings, and control data and access statements. Many of these capabilities are implemented by using one of three SQL categories: Data Definition Language (DDL), Data Manipulation Language (DML), and Data Control Language (DCL).

Microsoft SQL Server continues to adhere to industry standards, and provides improved ANSI SQL support and language enhancements that include declarative referential integrity (DRI) and powerful server-based cursor support, which far exceed the ANSI standard. SQL Server version 6.x enhances several existing Transact-SQL language statements and builds upon its existing tools and system procedures.

Transact-SQL commands are executed within the utilities provided by Microsoft, as well as in third-party applications that support Embedded SQL. Microsoft provides you with several utilities in which Transact-SQL statements and procedures can be executed:

  • isql. Provides a query interface you can use to perform system administration tasks from a server or a workstation. You can also use isql to create scripts for automating tasks.
  • ISQL/w. Provides a graphical query interface in which you can enter Transact-SQL statements and system-stored procedures. ISQL/w also provides a graphical way to analyze queries.
  • SQL Enterprise Manager. Provides easy, enterprise-wide management from a server or a workstation of SQL Server and SQL Server objects.

The Microsoft SQL Server Transact-SQL Reference contains information about all Transact-SQL statements, server-supplied stored procedures, and utilities. Syntax, limitations and restrictions, examples, and references to topics of similar interest are provided. For information about writing client applications that interact with the utilities, see the Microsoft SQL Server Programmer's Toolkit documentation in the "Database and Messaging Services" section of the Platform SDK.


Developing Microsoft Systems Management Server Applications

This section provides a brief overview of some of the important topics to consider when developing applications that interact with Microsoft® Systems Management Server (SMS). For additional information about Microsoft SMS functionality, or about development specifications and guidelines, see the Microsoft SMS documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Introduction to Microsoft Systems Management Server

Microsoft® Systems Management Server (SMS) provides complete, centralized desktop system administration, managing administrative tasks in the following areas: SMS database access, SMS inventory extension, SMS API, SMS distributable programs, SMS console application integration, SMS administrator extension, and Network Monitor extension.

SMS organizes computers into a hierarchy of sites. A site is a group of servers and client computers typically located in a single geographic area. A site can consist of one or more domains, that is, a set of servers and clients that are managed as a group, existing on the same LAN.

SMS uses the terms central, primary, and secondary to identify the capabilities of sites in the hierarchy. A central site is a primary site at the top of the hierarchy, from which all sites and computers in the hierarchy can be administered.

A primary site has its own Microsoft® SQL Server database, which contains all of the hardware and software inventory information for the site and its subsites (sites attached below it in the hierarchy). The primary site can run the Systems Management Server Administrator tool for local administration of the site server and all subsites. A primary site must be running Microsoft® Windows NT® Server.

A secondary site does not have an SQL Server database or the SMS Administrator tool. This site is administered from any site above it in the hierarchy and has no subsites. A secondary site must be running Windows NT Server.

A primary site can have either secondary sites or other primary sites beneath it in the hierarchy. A secondary site must have a primary site above it and can have no sites below it.

The SMS Software Development Kit (SDK) provides developers with tools to extend the SMS system and create applications that take advantage of its functionality and resources.

Using the SMS SDK you can:

  • Access the SMS site database. The SMS SDK offers samples of accessing the SMS site database by using other applications—such as Microsoft® Word, Microsoft® Excel, and Microsoft® Access—through the Open Database Connectivity (ODBC) SMS program, SMSVIEW.
  • Extend the SMS inventory and add objects with custom architectures, add a new object to an existing architecture, or add groups to existing computers in the SMS database.
  • Use the SMS API to gain access to objects in the SMS site database including computers, machine groups, site groups, software distribution packages and jobs, and SMS queries.
  • Create SMS distributable applications. You can write setup programs or scripts that will distribute and run with SMS.
  • Integrate third-party and ISV applications with SMS, making them available for launch from the SMS Administrator console.
  • Extend the Administrator interface by creating custom objects and icons.
  • Extend the set of Network Monitor protocols that display network traffic by creating protocol parser DLLs.


System Requirements and Recommendations for SMS

To develop applications for Microsoft® Systems Management Server (SMS), the following hardware is recommended:

  • Intel 80486/25 or higher processor; Intel Pentium or Pentium Pro processor; RISC-based microprocessors such as MIPS R4000 and Digital Alpha AXP; or PowerPC
  • Super VGA (800 x 600) 256-color display
  • At least 100 MB space on the partition containing Windows NT Server files
  • CD-ROM drive
  • 32 MB RAM or more
  • Network adapter card

In addition to the recommended hardware, the following software is required:

  • Microsoft® Windows NT® Server version 3.5 or later
  • Systems Management Server version 1.1 or later
  • Microsoft® BackOffice™ Software Development Kit (SDK)

Applications using the SMS API are compatible only with primary site databases for SMS version 1.1 or later. Sites running SMS version 1.0 are not supported.


Accessing the SMS Site Database

Microsoft® Systems Management Server (SMS) includes the Open Database Connectivity (ODBC) SMS program, SMSVIEW (SMSVIEW.EXE), which you can use to create database views on a site database. Using the Microsoft® ODBC Driver Kit, you can use these views in other applications (such as Microsoft® Word) to view the computer inventory and generate reports.

The SMS SDK provides samples for viewing, extracting, and using the computer inventory and other information in the site database. Samples are provided for Microsoft® Word for Windows version 6.0, Microsoft® Excel version 5.0, and Microsoft® Access version 2.0.

The SMS system database stores computer inventory in multiple tables for efficiency. However, this efficient design can make it difficult to view the computer inventory directly from other applications.

The inventory for each computer is stored in the MachineDataTable table. However, the specific inventory data (such as group names, attribute names, and the values for groups and attributes) is stored in other tables. The MachineDataTable table has keyed pointers to these other tables.

The SMSVIEW program creates views based on a dynamic table in the SMS database that lists all groups and attributes currently in the database. The inventory reported by the Inventory Agent (which runs at each SMS computer and reports the computer's inventory to the site database), and custom Management Information Format (MIF) files, determine which groups and attributes are contained in the database.

As a result, SMSVIEW can create additional views (or views with additional fields) based on the groups and attributes that have been reported to your particular site database. Or SMSVIEW can create a set of views that does not include the common views or fields listed in the table because inventory information for those groups or attributes has not been reported to your site database.

It is strongly recommended that you run the SMSVIEW program periodically to generate views that reflect the current groups and attributes in the site database. This is particularly important if a new attribute or group has been reported or if a group has been deleted.

For more information about using the SMSVIEW program to access the SMS site database, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Extending the SMS Inventory

The Microsoft® Systems Management Server (SMS) inventory is a database of all objects in your administrative system. To help you store and manage inventory information, SMS provides the following predefined architectures: Personal Computer, SMSEvent, PackageLocation, JobDetails, and UserGroups. If these predefined architectures do not meet your requirements, you can extend the inventory by defining custom architectures.

The significant issues related to inventory architecture, composition, and design are:

  • Structuring the inventory
  • Utilizing and automatically generating Management Information Format (MIF) files
  • Collecting inventory information
  • Using inventory history
  • Employing the desktop management interface
  • Incorporating custom architectures

For more information about inventory topics, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Inventory Structure

In a Microsoft Systems Management Server (SMS) site database, the inventory has a hierarchical structure. An architecture is a standard structure for establishing inventory for a set of related objects, and is defined by the Architecture group and specified by a unique architecture name. An object is a specific item with a specific architecture that is stored in the inventory database.

Each object is composed of structures called groups, which define distinct parts of the object. A group combines a set of attributes into a single, identifiable entity. Finally, attributes are the properties of a group and are assigned values, which when considered in totality, make up the inventory for the object.

For example, a specific computer can be included in the inventory database as an object of the Personal Computer architecture. On this computer, you can define specific groups such as Processor, Disk, and Operating System. The Disk group may have attributes such as Drive Index, Storage Type, and Free Storage.


Management Information Format

To add or maintain items in a Microsoft Systems Management Server (SMS) database, the SMS system uses data in the Management Information Format (MIF). MIF files are ASCII text files that allow you to add objects with new architectures (for example, printers or hardware routers) to the SMS database; add new objects (for example, a new computer to the Personal Computer architecture) with existing architectures; and add new groups and attributes to existing objects.

You can also extend the SMS Administrator to display custom graphics for custom objects and groups in its Sites window and Properties window. If you want the new object to appear in the Sites window of the SMS Administrator, you must define at least seven specific attributes in the Identification group.


Inventory History and Collection Process

When the Inventory Agent runs at a Microsoft Systems Management Server (SMS) computer, it reports the inventory to an SMS logon server as a binary file. This file, called a RAW file, contains the computer's inventory in the Management Information Format (MIF) file. When the Inventory Processor processes a RAW file, it parses the RAW file (verifying the MIF syntax) and compares the inventory reported in the RAW file with the inventory history for the computer. If there are changes, the Inventory Processor creates a Delta-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 Delta-MIF file, it then adds, updates, or deletes the groups specified in the Delta-MIF file in the SMS database.


Desktop Management Interface

In general, the Microsoft Systems Management Server (SMS) system can use any Management Information Format (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 unique way. Although the full DMI 4.5 syntax is accepted by the SMS MIF parser, some fields are not used, and the SMS system may use some of the information in a way that differs from the DMI 4.5 Specification. For example, the DMI 4.5 Specification permits only one component per MIF file whereas SMS supports multiple components.


Custom Architectures

You can extend the inventory beyond the architectures already defined in the Microsoft Systems Management Server (SMS) system by adding objects with new (custom) architectures. A custom architecture can store information about objects that have little or no relationship to the predefined SMS architectures.

To add an object with a custom architecture to the inventory, you use a Management Information Format (MIF) file. In the MIF file you include the properties of the object and define the structure of the architecture. The structure of the architecture is defined by the attributes you include in the Identification and Architecture groups, and by the other groups and attributes that you choose to include in the MIF file.


Automatic MIF File Generation

The Microsoft Systems Management Server (SMS) MIF Form Generator and the SMS MIF Entry utility let users at SMS clients add new groups to their computers' inventories. MIF forms, designed using the SMS MIF Form Generator, set up the structure of the group: its name, class, and attributes. After they are designed, you can distribute the forms to SMS clients, where users complete the forms by using the MIF Entry utility. The SMS system then collects the MIF files generated by the users who completed the forms, and adds the groups included in the MIF files to the inventory of the users' computers in the site database.

For example, you can use the SMS MIF Form Generator to create a form for an Employee Information group that stores user information such as full name, location, room number, phone number, employee identifier, division, and so on.


Using the SMS API

In a Microsoft® Systems Management Server (SMS) system, the database for a primary site stores the inventory and configuration information for itself and the sites below it in the site hierarchy. The SMS API provides a C-language interface that enables your application to retrieve, add, and remove data in the SMS database.

You can use the SMS API to gain access to objects in an SMS database, such as sites, inventoried objects, packages, jobs, queries, machine groups, and site groups.

All SMS objects are represented by the SMS API as containers, folders, and scalars. This model provides a standard interface to all types of objects within the Systems Management Server. The SMS API supports the concept of filters to regulate object selection. Filters define the criteria used to select the objects you want to find and are configured using tokens.

The following topics present the issues significant to designing applications that take full advantage of the SMS API. For more information about these topics, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


About Containers

The Microsoft Systems Management Server (SMS) API accesses objects in a site database by retrieving information about those objects and storing it in containers. After your application has populated a container with objects from a site database, the application can access those objects and their properties.

There are six different types of containers for objects: C_SITE, C_MACHINE, C_PACKAGE, C_JOB, C_MACHINEGROUP, and C_SITEGROUP. Structurally, the instance of an object within a container is represented as a folder.

Before your application populates a container, it can set filters on the container. Filters specify the objects to retrieve from the site database and store in the container. If no filter is set for a container, all objects (of the type supported by the container) are returned when the container is populated.


About Folders and Scalars

Within a container, the instance of an object is represented as a folder. For example, a C_SITE container can contain a set of F_SITE folders that represent the current site (the site whose Microsoft Systems Management Server (SMS) database your application is accessing) or sites below the current site in the site hierarchy.

Because some objects can contain multiple components, a folder can also contain subfolders. For example, a site folder can contain subfolders for the domains in the site and any subsites below that site in the site hierarchy.

Additionally, a folder can contain scalars, or a combination of subfolders and scalars. A scalar is the value stored for an attribute of a folder. For example, the folder for a site contains scalars for site name, parent site, depth, status, site type, and detailed status. The folder for a specific site would have a specific value for each scalar. In addition to a value, each scalar also contains a name, a data type, and an access mode.

The set of scalars that a folder can contain is determined by the folder type. Except for group folders, the set of scalars for all folder types is predetermined by the SMS API. Group folders contain scalars that represent attributes for an inventoried item. However, there is no defined set of scalars for group folders in general.

The set of scalars within a group folder depends on its group class and on the instance of the group. All attributes defined for the group may not have been included by the MIF file that reported the inventory.


About Filters and Tokens

Filters define the criteria used to select the objects that are retrieved from a Microsoft Systems Management Server (SMS) site database. Functionally, one or more filters can be set on a particular container before the container is populated by your application.

There are two classes of filters:

  • Transient filters, which are created by your application and that exist only for the lifetime of the process that created them.
  • Persistent filters within a filter container, which have been added to the site database. Persistent filters can be loaded by other processes, can contain scalars that are used to label the filter within the site database, and cannot be deleted from the SMS site database using the SMS API.

To assist you in configuring a filter, the SMS API provides you with the ability to add tokens to the filter. Within a filter, multiple tokens can be connected and joined using the logical operators, AND or OR. There are two types of token: expression and control.

An expression token defines how to search for objects that have a specified relationship to a determined value for a given attribute. An expression token consists of an attribute, a relational operator, and a comparison value. The relational operator (such as "is equal to" or "is like") defines how the specified value should be compared with the actual value stored for the given attribute.

A control token can be a logical operator or parentheses. A logical operator connects two expression tokens, two subclauses, or a combination of an expression and a subclause. A logical operator defines the relationship between two adjacent expressions or subclauses.


SMS Distributable Programs

When creating a new software package to run in a Microsoft® Systems Management Server (SMS) environment, you must include a setup or installation program that supports the requirements of the SMS environment. You must also include a package definition file (PDF) that contains predefined Workstation, Sharing, and Inventory property settings for your package, and a package directory structure containing the files required to support the installation options in the PDF.

The following topics present an overview of the software installation/deinstallation process, define the SMS requirements for installation programs, describe the package command status MIF file, outline the PDF format, and describe using SMS jobs to install packages.

For more information about these topics, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Overview of Installation

The installation of software in the Microsoft Systems Management Server (SMS) environment starts with the collection of inventory information from computers throughout the organization. This hardware and software inventory information is stored in the SMS database and used to plan and control the installation process.

SMS distributes software throughout an organization in the form of packages. These packages define the components to be installed, the supported platforms, and various configuration options for the software.

SMS installs software by using jobs that target specific sets of computers and define the mechanics of the distribution through the SMS hierarchy. A job defines a set of computers called distribution servers, which act as staging points in the hierarchy for packages. After a package is present on the distribution servers, the job is sent as a control file to the target clients, where it is executed by a component of the SMS client code called the Package Command Manager (PCM).

To install software in an SMS environment, use the following general procedure
  1. Create a setup or installation program.
  2. Create a PDF.
  3. Create a package directory.
  4. Import the software package into the SMS environment.
  5. Use an SMS job to install the package.
  6. Write a package command status MIF file in the Windows directory.

The same rules apply when maintaining packages.

Removing software requires a deinstallation program, which can be a command-line switch on your main setup program. A package command status MIF file must also be written in the Windows directory.


SMS Installation Requirements

A software setup or installation program used in the Microsoft Systems Management Server (SMS) environment must support that environment by:

  • Operating in unattended mode. It is mandatory that the program not require user input during the installation, removal, or maintenance of the application. Any information or options required by the setup program should be supplied by command-line switches to the program, or should be provided in a configuration file that is read by the program at run time or by some other means such as the Microsoft® Windows NT® registry. Your application must not show any dialog boxes or windows during installation/deinstallation or maintenance.
  • Not forcing the operating system to restart. Because multiple packages can be installed by SMS at one time, no individual package installation should force the operating system to restart as part of its installation program. Instead, the Package Command Manager (PCM) has the capability of intercepting and queuing restart requests until all packages have been installed, offering the user the opportunity to save any work in progress before the operating system is restarted.
  • Passing restart instructions to the PCM. To copy system files that may be in use, setup programs typically construct a batch file containing operations that must be performed during a restart of the operating system, such as running a Microsoft® MS-DOS® program by using ExitWindowsExec, and then restarting Microsoft® Windows®.
  • Reporting status to SMS using a package command status MIF file. To report the status of a PCM application installation, a Management Information Format (MIF) file must be created in the Windows directory.


The Package Command Status MIF File

To report the status of a Package Command Manager (PCM)-spawned application installation or deinstallation, a package command status Management Information Format (MIF) file must be created in the Windows directory.

The MIF file name must be unique so that multiple installations in a single session can report their status without a conflict in the name of the MIF files. The creation date and time stamp of the MIF file must be set to a time after PCM started to run the job. In this way, PCM knows that the MIF file was placed there by your setup program and will update the Microsoft Systems Management Server (SMS) database with the values the file provides.

SMS provides two DLLs to assist ISVs in writing package command status MIFs: ISMIF32.DLL, for use on 32-bit machines, and ISMIF16.DLL, for use on 16-bit machines. Programs started by a package command can call a function from these DLLs that creates the MIF file in the Windows directory with the correct date and time stamp.

SMS also provides a tool, ISMIF, that writes a generic status MIF from information given through a command line and/or a dialog box.


Using Package Definition File Format

A package definition file (PDF) is an ASCII text file that contains predefined Workstation, Sharing, and Inventory property settings the system uses for a package. A PDF follows the standard initialization file format containing keys (the key names are enclosed within square brackets and separated by spaces), where each key contains one or more entries. A PDF has specific keys and entries that are used by the system to set the properties of a package.

Important keys include:

  • The [PDF] key, which identifies the file as a package definition file.
  • The [Package Definition] key, which defines the overall properties of the package.
  • For the setup variations specified in the SetupVariation entry in the [Package Definition] key, the PDF must have a key that defines each variation.
  • The [Setup Package for Sharing] key, which defines the Sharing properties of the package.
  • The [Program Item Properties Index] key, which specifies the program item properties for network applications contained in the package. Each program item will be defined in the package's Sharing property.
  • The [Setup Package for Inventory] key, which defines the Inventory properties of the package.
  • For the files specified in the PackageDetectionRule 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 and has the form of [File index].
  • The inventory rules for a package must define that package uniquely among all other packages that may be installed on a machine. You can use a prodspec.INI file in conjunction with the Inventory section of the PDF to increase the accuracy of package recognition. A prodspec.INI file uses the standard .INI file format and contains sections and keys that, taken together, uniquely define a specific version of a product.


Using SMS Jobs to Install Packages

Microsoft Systems Management Server (SMS) uses jobs to distribute packages to target systems. There are various job options that you can specify, depending on the type of job that you are creating. The main options that affect the distribution of software are the specification of targets, the distribution servers where the package will be made available, and the options for the run phase of the job.

There are three primary types of jobs to distribute packages:

  • Run Command on Workstation jobs, which run on the target clients in the context of the package share that is associated with the job. They are the most common type of job used in SMS to install, remove, and maintain software on target clients.
  • Share Package on Server jobs, which are 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.
  • Remove Package From Server jobs, which are used to remove packages from SMS site servers, distribution servers, and servers that have had a package installed using the Share Package on Server job. These jobs do not remove packages from clients; that is performed using deinstall options for the Run Command on Workstation job.


Console Application Integration

Microsoft Systems Management Server (SMS) provides support for launching ISV applications from a Tools menu in the SMS Administrator console in a context-specific manner. (The term context refers to the internal class name of the SMS multiple document interface (MDI) window that has the focus.)

Launching an application from the SMS Administrator requires adding data about the application under the following key in the Windows NT registry:

SOFTWARE\Microsoft\SMS\Applications

This key is located under both HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE. Applications registered under HKEY_LOCAL_MACHINE are available to all SMS users; applications registered under HKEY_CURRENT_USER are available only to the user who registered the application.

The registered data defines the characteristics of the application by specifying the command description, command name, command-line arguments, and so on.

SMS provides a command-line utility, SMSADDIN.EXE, that creates or removes the required registry settings based on command-line arguments and a data file.

SMS supports ISV application launching for several contexts. Applications registered in the General context are always available from the Tools menu regardless of the current context. Applications registered in a specific context are only available when that context is active (that is, when that context's corresponding MDI window has the focus). You can register applications in more than one context.

Registered applications are displayed in the Tools menu in the SMS Administrator console. When the user selects an application from the Tools menu, SMS forms a command line from the application's registry data and passes the command line to the underlying operating system for execution.


Registry Keys and Values

The Windows NT registry keys and values required for ISV application launching are as follows:

  • Microsoft Systems Management Server (SMS) Applications Key (HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER)
  • Vendor Key, which is the full name of the vendor.
  • Application Key

    This key can contain values for the application name, application description, the name of the executable launched when the application is selected from the Tools menu, the directory from which the application will start, the state of the launched application, and the order in which the application will appear in the Tools menu.

  • Context Keys

    These keys specify whether the application is available in the General context or a specific context. An application can be registered in more than one context. Each context key contains additional values that specify when the application will be present in the Tools menu, when the application will be present but disabled, and the arguments to be passed on the command line that launches the application.


Using the Application Registration Tool

Microsoft Systems Management Server (SMS) provides a command-line utility, SMSADDIN.EXE, to assist ISVs with registering their applications for launching from the SMS Administrator console.

You use SMSADDIN.EXE interactively to create and test the application's registry data, then save that data in a Add-in Tool Definition (.ATD) file. When used interactively, SMSADDIN.EXE displays a window in which you can enter all the required registry information.

After creating the .ATD file, you modify the application's setup program to run SMSADDIN.EXE in unattended mode, passing the .ATD file. When run during setup, SMSADDIN.EXE checks the syntax of the .ATD file and writes the registry silently.

You can also use SMSADDIN.EXE to unregister applications.

SMS also provides sample code that adds or deletes applications the same way as SMSADDIN.EXE. ISVs can build this code into their setup programs as an alternative to running SMSADDIN.EXE from setup.


Extending the SMS Administrator

The Microsoft® Systems Management Server (SMS) Administrator assists the user in identifying objects in a list and in differentiating between various properties. This functionality is provided through a rich graphical interface and can be extended or overridden using resource-only DLLs.

Specifically, when the SMS Administrator displays an object of a particular architecture (such as a computer with the Personal Computer architecture) within a window, it displays identifying graphics for that object and architecture. Inventoried objects can be displayed within the Sites, Machine Groups, and Query Results windows.

In addition, the detailed properties of an object can be viewed by using a machine properties window. In the SMS Administrator, the user can view the properties of an inventoried object by selecting the object in a Sites, Machine Groups, or Query Results window, and then choosing Properties from the File menu. The properties of the object are displayed in a machine properties window. The properties are represented as attributes that have a name and a value. Related attributes are grouped together into groups. The user can view the attributes by group by selecting the group to view in the Properties pane; the attributes for the group are then displayed in the right pane. Each group has a graphic that represents it within that particular architecture.

For example, a computer object in an SMS site database is displayed according to its architecture, system type, and role. So, a computer with a Personal Computer architecture, Macintosh system type, and Workstation role would be displayed in the Sites window using the graphic for that particular architecture, system type, and role. The same graphic would also be displayed if the Macintosh workstation were displayed in a Query Results window. The properties of a Macintosh computer would be displayed in a Personal Computer Properties window and the Identification group would be represented in the Properties pane by the graphic for that particular group in that particular architecture.

When new architectures, new types of objects, or new properties are added to the SMS inventory, the SMS Administrator uses the default graphic to display these items if no resource-only DLL is supplied. For example, the sample MIF file for a printer object with the Printer architecture is represented by the default icon when it is displayed in the Sites window if no resource-only DLL is supplied. In addition, the groups for a custom Printer object are represented in a Printer Properties window by the default graphic if no resource-only DLL is supplied.

The following topics provide an overview of resource-only DLLs, as well as detailed information you would need to develop applications that take advantage of resource-only DLL functionality. For more information about these topics, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Resource-only DLLs

Using resource-only DLLs and the Microsoft® Windows NT® registry, you can override the graphics of existing architectures, objects, and groups. You can provide graphics for new architectures, objects, and groups that have been added to the Microsoft Systems Management Server (SMS) inventory by using custom Management Information Format (MIF) files. When new architectures, new types of objects, or new properties are added to the SMS inventory, the SMS Administrator uses the default graphic to display these items if no resource-only DLL is supplied.

The set of DLLs can be specified using the following registry keys:

HKEY_LOCAL_MACHINE\Software\Microsoft\SMS\ResDLLs

HKEY_CURRENT_USER\Software\Microsoft\SMS\ResDLLs

When the SMS Administrator searches for display graphics in the resource-only DLLs, it searches the DLLs in the following order:

  1. DLLs listed in HKEY_LOCAL_MACHINE. The SMS Administrator uses the reverse of the order listed in the installed value to search the DLLs.
  2. DLLs listed in HKEY_CURRENT_USER. The SMS Administrator uses the reverse of the order listed in the installed value to search the DLLs.
  3. MS Administrator's own application resources. Some architectures, objects, and groups (such as the Personal Computer architecture, Macintosh workstation computers, and the Processor and Disk groups) have graphics predefined in the SMS Administrator's resources. However, these graphics can be overridden by a resource-only DLL.

Because the graphic for an item may have more than one available format, the SMS Administrator may search the list of resources several times. For example, if the SMS Administrator needed to display a Macintosh workstation, it would first search for a graphic for the specific architecture, system type, and role in all resources. In this case, the resource name would be Personal_Computer_Macintosh_Workstation. If the resource with this name is found, the SMS Administrator uses that graphic. If no resource with this name is found, it searches for the graphic for the architecture and role. In this case, the resource name would be Personal_Computer_Workstation. If no resource matching this name is found, the SMS Administrator searches for the graphic for the architecture. In this case, the resource name would be Personal_Computer_None. If no resource matching this name is found, the default graphic is displayed.


Resource-only DLLs for Custom Graphics

Using resource-only DLLs, you can control the graphics displayed by the Microsoft Systems Management Server (SMS) Administrator for architectures and objects within the Sites, Machine Groups, and Query Results windows. You can also control the graphics for the properties within machine properties windows. The two types of graphics are architecture bitmaps and machine property icons.

Architecture Bitmaps

For each object of each architecture, the SMS Administrator displays a 16-by-16-pixel bitmap that represents that specific object within that specific architecture. These architecture bitmaps are displayed in the Sites, Machine Groups, and Query Results windows.

Using a resource-only DLL, you can override the default graphics for existing architectures and objects or add custom graphics for new types of architectures or objects. If a new architecture or new type of object is added to the SMS inventory and no resource-only DLL is provided, the default graphic is displayed.

A mask bitmap explicitly specifies the pixels to display with the highlight color (if the object is selected) or the background window color (if the object is not selected). The SMS system generates a mask bitmap for each architecture bitmap. However, you can also specify a mask bitmap. The mask bitmap is white where you want the highlight color or background window color to show through the bitmap, and black where you want the bitmap to show.

Machine Property Icons

Machine property windows are used to display the properties of an inventoried object. The properties are organized into groups, and the groups contain attributes. The user can view the attributes by group by selecting the group to view in the Properties pane; the attributes for the group are then displayed in the right pane. Each group has a graphic that represents that particular group within that particular architecture.

Using a resource-only DLL, you can override the default graphics for existing groups or add custom graphics for new types of groups. If a new group is added to the SMS inventory and no resource-only DLL is provided, the default graphic is displayed.


Using Resource-only DLLs in SMS Administration

To enable the Microsoft Systems Management Server (SMS) Administrator to use the graphics in a resource-only DLL, you must install the DLL and add keys to the Windows NT registry of the computer where the SMS Administrator is installed.

To install resource-only DLLs for the SMS Administrator, use the following general procedure.

  1. Install the resource-only DLLs in a directory that is in the path of the computer where the SMS Administrator is installed. Optionally, you can place the DLLs in their own directory and specify a fully qualified path when you configure the Windows NT registry to complete the installation of the DLL.
  2. After proper installation of the DLL, add keys that specify the DLLs to the Windows NT registry of the computer where the SMS Administrator is installed. The set of DLLs can be specified using the following registry keys:
    • HKEY_CURRENT_USER\Software\Microsoft\SMS\ResDLLs. Specifies the resource-only DLLs to be used only by the current user. The SMS Administrator searches for a resource in the list of DLLs in this key first.
    • HKEY_LOCAL_MACHINE\Software\Microsoft\SMS\ResDLLs. Specifies the resource-only DLLs to be used by any user on that computer. If the resource is not found in the DLLs in HKEY_CURRENT_USER, the SMS Administrator searches for a resource in the list of DLLs in this key.
  3. If the SMS Administrator is running, exit and then restart it.

Other important installation issues exist, such as determining the search order for the resource-only DLLs and the correct administration of directories that can be purged, and should be examined in detail as they relate to your system.


Extending the Network Monitor

Network Monitor displays protocol information for network administrators to use when viewing network traffic and troubleshooting problems. By writing custom protocol parsers, you can extend the set of protocols for which information is displayed in Network Monitor.

Protocol parsers read through raw network frames (packets of network data), locating specific protocol headers within the data stream, attaching descriptions (properties) to each of the header's fields, and identifying those properties to the Network Monitor kernel. Network Monitor then displays the captured data and the properties attached by the parser, to help the network administrator understand the data. Note that you must not use any threads, or APIs that will not run on Microsoft® Win32s®, in your parser.

Before attaching properties to the raw data, a parser must first register all possible properties with the Network Monitor kernel. The parser tells the kernel to create a property database, and then fills the property database with all of the possible properties for its protocol. Each property in the property database contains information such as a textual description, a data type and qualifier (used to format the raw data), and a formatting routine for displaying the data.

The creation of a parser is a multi-step process ranging from simple, environment-building tasks, such as setting up Microsoft® Visual C++® or the Platform SDK, to those specific to Microsoft Systems Management Server (SMS) such as editing SMS source and header files.

The following topics present an overview of the important issues you should address when developing parser DLLs to extend Network Monitor. For more information about these topics, see the Microsoft Systems Management Server documentation in the "Setup and Systems Management Services" section of the Microsoft Platform SDK.


Using Entry Point Functions in Protocol Parser DLLs

Every parser DLL must have five entry points:

  • Register( ), which builds the property database by making calls to CreatePropertyDatabase( ), and then passes the database back to the kernel.
  • Deregister( ), which allows a parser to clean up by calling DestroyPropertyDatabase on its property database.
  • RecognizeFrame( ), which takes a pointer to raw data and passes back to the kernel whether or not the parser recognizes the data; if the parser does recognize the data, it also passes back the length of the recognized data.
  • AttachProperties( ), which identifies every displayable element of the recognized frame.
  • FormatProperties( ), which asks the parser to take all of the property instances and build the PropertyText field in each PropertyInst structure.


About Functions Called by Parser DLLs

The following functions can be called by a parser DLL to perform administrative and functional tasks:

  • AddProperty, which is used to add a PropertyInfo structure to the PropertyDatabase.
  • AttachPropertyInstance, which is used to attach a property instance to a frame.
  • AttachPropertyInstanceEx, which also is used to attach a property to a frame (however, this function creates an additional structure).
  • CreatePropertyDatabase, which is used by a parser to create a property database for describing properties that the parser will use to describe its data.
  • DestroyPropertyDatabase, which is used to destroy a property database created by calls to CreatePropertyDatabase and AddProperty.
  • GetFrameDestinationAddress, which returns a frame destination address.
  • GetFrameSourceAddress, which returns a frame source address.
  • GetProtocolStartOffset, which returns the offset to a specified protocol in the frame.
  • FindPreviousFrame, which finds the previous frame in the current capture context that matches the filter.
  • FindNextFrame, which finds the next frame in the current capture context that matches the filter.
  • FormatPropertyInstance, which formats the property instance in a generic manner.
  • ParserTemporaryLockFrame, which returns a pointer to the first byte of data in the locked frame.


Structures Used Within Parser DLLs

The following structures are used within parser DLLs to assist functions performing administrative and functional tasks:

  • LABELED_BYTE, which is used to represent a value/label pair. You can create a table of these value/label pairs and point a SET structure to it to make a set of LABELED_BYTE structures.
  • LABELED_WORD, which is used to represent a value/label pair. You can create a table of these value/label pairs and point a SET structure to it to make a set of LABELED_WORD structures.
  • LABELED_DWORD, which is used to represent a value/label pair. You can create a table of these value/label pairs and point a SET structure to it to make a set of LABELED_DWORD structures.
  • SET, which is used to represent a table of values for a property. The first field is a count, and the rest of the entries can interpret the data pointed to as a BYTE, WORD, DWORD, LABELED_BYTE, LABELED_WORD, or LABELED_DWORD structure.
  • RANGE, which is used to represent a valid range for a number.
  • LABELED_BIT, which is used to handle bitfields or flags. The data type will almost always be found in conjunction with a SET data type.
  • PROTOCOLINFO, which is used to contain comments on a protocol.
  • PROPERTYINFO, which is used to describe the properties that the protocol parser needs to describe the frames.
  • PROPERTYINST, which is used to represent an instance of a property in a frame. If PropertyInst->Length is set to 0, then the lpPropertyInstEx structure points to a PROPERTYINSTEX structure defining free-form property instance data.
  • PROPERTYINSTEX, which is used to describe a free-form extended property instance when the actual data is in a proprietary format.


Developing Microsoft SNA Server Applications

This section provides a brief overview of some of the important topics to consider when developing applications that interact with Microsoft® SNA Server. For additional information about SNA Server features, or about development specifications and guidelines, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Introduction to Microsoft SNA Server

Although simple one-to-one connections can suffice for many basic computing operations, most organizations require more flexible connectivity between IBM host computers and local area networks (LANs). To meet this need, Microsoft® Systems Network Architecture (SNA) Server exploits client/server architecture to link personal computers to IBM mainframe and midrange computers, such as the IBM AS/400 series, which are accessible using the SNA protocols. The client personal computers can run the Microsoft® Windows NT®, Windows® 95, Windows® version 3.x, or MS-DOS® operating systems, OS/2, or the Apple Macintosh operating system, and can use standard LAN protocols to connect to the server; only the computer running SNA Server must run the SNA protocol. Each personal computer user can have multiple 3270 sessions for concurrent terminal and printer emulation.

The client/server architecture of SNA Server allows the removal of communications processing from client systems so their system resources can be used more efficiently. Client personal computers do not have to run one protocol to access the LAN and another to access the SNA host. Each personal computer can run Microsoft-based networking (named pipes), TCP/IP, IPX/SPX, AppleTalk, or Banyan VINES, within a single-protocol or mixed network, to access SNA Server. SNA Server routes the connection to the appropriate host computer by way of the SNA protocol. The client/server architecture also provides Windows NT, Windows 95, and Windows 3.x applications with the ability to access information on IBM mainframes and midrange computers.

All hardware platforms supported by Windows NT can be integrated with Microsoft SNA Server. SNA Server relies on the built-in security of Windows NT, so administrators can manage a single set of user accounts. SNA Server is also fully integrated with Windows NT system monitoring and management services, and provides automatic server and connection fault tolerance. Microsoft Windows SNA Server has a complete 32-bit, multithreaded architecture designed for maximum performance, scalability, and reliability. Also, SNA Server is fully compliant with the Microsoft Windows Open Services Architecture (WOSA), providing a consistent interface to organization computing environments and hiding the complexities of connectivity from applications.

Microsoft SNA Server provides support for the following APIs for distributed SNA applications:

  • Advanced Program-to-Program Communications (APPC) for applications that communicate peer-to-peer with other APPC applications using the logical unit (LU) type 6.2 protocol.
  • Common Programming Interface for Communications (CPI-C) for applications that communicate peer-to-peer with IBM Systems Application Architecture (SAA) applications using the LU type 6.2 protocol.
  • Logical Unit Application (LUA) programming interfaces for applications (using LUA/Request Unit Interface or LUA/Session Level Interface APIs) that need direct access to LU types 0, 1, 2, and 3 data streams.

With the Microsoft SNA Server Software Development Kit (SDK) you can design applications that use SNA Server APIs, such as APPC or CPI-C, or the 3270 emulation client. The following sections present an overview of the SNA Server SDK and clarify the significant APIs and development issues for you to create effective SNA Server applications.


System Requirements and Recommendations for SNA Server

Different requirements exist for Microsoft® SNA Server and SNA Server client applications. The following topics discuss these requirements.


Requirements for Microsoft SNA Server Applications

To develop server applications for SNA Server, the following hardware is required:

  • Minimum of 20 MB of total system RAM. This value is 4 MB more than the required minimum for Windows NT Server. It is highly recommended that the server be equipped with enough RAM for optimal performance and for situations where loads are heavy.
  • Minimum of 11 MB free hard-disk space.
  • Network adapter.
  • Supported SNA communications adapter(s).

In addition to the required hardware, the following software is required:

  • Microsoft Windows NT Server version 3.5 or later.
  • Network software and protocols, including one or more of the following: Microsoft networking (the network software included in Windows NT), NWLink or equivalent IPX/SPX services, Microsoft TCP/IP or the equivalent Microsoft Win32 Windows Sockets version 1.1 interface, Banyan VINES Enterprise Client version 5.52 or later for Microsoft Windows NT, and services for the Apple Macintosh.


Requirements for Microsoft SNA Server Client Applications

There are a variety of hardware and software requirements for developing SNA Server client applications depending on the client development platform. The following topics discuss these requirements.


Developing for the Microsoft Windows NT Environment

To develop client applications for SNA Server in a Windows NT environment, the following hardware is required:

  • Minimum of 14 MB of total system RAM. This is 2 MB more than the required minimum for Windows NT Workstation.
  • Minimum of 7 MB free hard-disk space.
  • Network adapter.

In addition to the required hardware, the following software is required:

  • Microsoft Windows NT Server version 3.5, or Windows NT Workstation version 3.5 or later.
  • Networking software and protocols, including one or more of the following: Microsoft networking (the network software included in Windows NT), NWLink or equivalent IPX/SPX services, Microsoft TCP/IP or equivalent Microsoft® Win32® Windows Sockets version 1.1 interface, and Banyan VINES Enterprise Client version 5.52 or later for Microsoft Windows NT.


Developing for the Microsoft Windows 95 Environment

To develop client applications for SNA Server in a Windows 95 environment, the following hardware is required:

  • Minimum of 6 MB of total system RAM. This is 2 MB more than the recommended minimum for Windows 95.
  • Minimum of 7 MB free hard-disk space.
  • Network adapter.

In addition to the required hardware, the following software is required:

  • Microsoft Windows 95.
  • Networking software and protocols, including one or more of the following: Microsoft networking (the network software included in Windows NT), NWLink or equivalent IPX/SPX services, Microsoft TCP/IP or equivalent Microsoft Win32 Windows Sockets version 1.1 interface, and Banyan VINES Enterprise Client version 5.52 or later for Microsoft Windows NT.


Developing for the Microsoft Windows 3.x Environments

To develop client applications for SNA Server in a Windows version 3.x environment, the following hardware is required:

  • Minimum of 4 MB of total system RAM.
  • Minimum of 4 MB free hard-disk space.
  • Network adapter.

In addition to the required hardware, the following software is required:

  • Microsoft Windows for Workgroups or Windows version 3.x.
  • Networking software and protocols, including one or more of the following: the networking software included in Windows for Workgroups; Microsoft® LAN Manager version 2.x; Novell NetWare (IPX.COM) version 3.10 or later, or any open data-link interface (ODI) driver; Microsoft TCP/IP or the equivalent Microsoft Win32 Windows Sockets version 1.1 interface or later; and Banyan VINES version 5.52 or later.


Developing for the MS-DOS Environment

To develop client applications for SNA Server in a MS-DOS environment, the following hardware is required:

  • Minimum of 640 kilobytes (KB) of total system RAM.
  • Minimum of 2.2 MB free hard-disk space.
  • Network adapter.

In addition to the required hardware, the following software is required:

  • MS-DOS operating system version 3.2 or later.
  • Microsoft LAN Manager version 2.x, Novell NetWare (IPX.COM) version 3.10 or later, or Banyan VINES version 5.52 or later.


Developing for the OS/2 Environment

To develop client applications for SNA Server in an OS/2 environment, the following hardware is required:

  • Minimum of 8 MB of total system RAM.
  • Minimum of 1 MB free hard-disk space.
  • Network adapter.

In addition to the required hardware, the OS/2 operating system version 1.21 or later is required.


Developing for the Macintosh Environment

To develop client applications for SNA Server in a Macintosh environment, the following software and hardware are required:

  • Apple Macintosh System 6.0.2 or later and Finder version 6.0 or later (System version 7.0 and Finder version 7.0 can be used).
  • Standard Macintosh platform with AppleTalk access.
  • Emulator software and any hardware or additional software required for that emulator.

For information about emulator software for the Macintosh, see the SNA Server Companion Product Catalog, ISVCATAL.DOC, in the \COLLATRL\3rdParty directory on the SNA Server compact disc.


APPC Programming and File Transfer

Advanced Program-to-Program Communications (APPC) is an application programming interface (API) that allows peer-to-peer communications in a Systems Network Architecture (SNA) environment. By using APPC, programs distributed across a network can work together—communicating and exchanging data—to accomplish a single processing task. A processing task can query a remote database, copy a remote file, or send or receive electronic mail, as well as perform other administrative tasks.


APPC Programming

APPC serves as a translator between applications and the network in a distributed environment. When an application on your computer passes information to the APPC software, APPC translates and passes the information to a network interface, such as a local area network (LAN) adapter card. The information travels across the network to another computer, where the APPC software receives the information from the network interface. APPC translates the information back into its original format and passes it to the corresponding partner application.

The following topics discuss the development issues relevant to APPC programming: understanding transaction programs, using APPC verbs, and understanding Common Service Verbs and Windows APPC extensions. For more information about these topics, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Understanding Transaction Programs

The part of an application that initiates or responds to APPC communications is called a transaction program (TP). A transaction program on a workstation is not a stand-alone program. Instead, it is the part of one application that handles transactions (exchanges of data) with another application. These programs communicate as peers, on an equal (rather than hierarchical) basis, and use APPC verbs to exchange status information and application data. Each TP uses APPC verbs to supply parameters to APPC, which performs the desired function and returns parameters to the TP.

Various hardware and software elements in the SNA environment are required for two TPs to communicate. Most importantly, for access to the network, each TP must be associated with a logical unit (LU) of type 6.2. The relationship between TPs and LUs is complex and developers must understand many terms including a mapped or basic conversation, a type of conversation used by application TPs; synchronous verb, an APPC verb that blocks further program operations until the processing of the verb is complete; and invokable TP, a TP that can be invoked by another TP.

The SNA Server documentation provides information about designing and coding TPs. Important topics include:

  • Conversation states
  • Confirmation processing
  • Asynchronous data receiving
  • Conversation security
  • Basic and mapped conversations
  • Invoking, and invokable, TPs


Using APPC Verbs

Communication between two transaction programs is accomplished using APPC verbs. These verbs fall into three categories:

  • Management verbs, which establish APPC LU 6.2 session limits and obtain configuration information and current operating values for the SNA node. The management verbs are CNOS (Change Number of Sessions) and DISPLAY.
  • Transaction program (TP) verbs, which initiate and terminate TP sessions. The TP verbs are GET_TP_PROPERTIES, SET_TP_PROPERTIES, TP_ENDED, and TP_STARTED.
  • Conversation verbs, which enable TPs to allocate and deallocate a conversation, send and receive data, and change conversation states. Conversation verbs fall into two groups: mapped and basic.


About Windows APPC Extensions and Server-Specific Enhancements

The Microsoft® Windows® APPC API extensions allow asynchronous communication within the SNA Server environment and have been designed for Windows 3.x and later versions (with the exception of Windows 3.0 operating in real mode). These extensions provide support for maximum Windows programming compatibility and optimum application performance in both 16-bit and 32-bit operating environments.

The following are the nine Windows APPC extensions: WinAsyncAPPC, WinAsyncAPPCEx, WinAPPCCancelAsyncRequest, WinAPPCCancelBlockingCall, WinAPPCCleanup, WinAPPCIsBlocking, WinAPPCStartup, WinAPPCSetBlockingHook, and WinAPPCUnhookBlockingHook.

Microsoft SNA Server also supports SNA Server-specific extensions to Windows APPC and Common Service Verbs (CSVs). The logical unit (LU) function GetAppcConfig takes a local mode pair and returns the remote LUs that are accessible to the user through that pair. The GetAppcReturnCode and GetCsvReturnCode functions provide a standard set of error strings for use by applications.


About Common Service Verbs and Extensions

In the SNA Server environment, Common Service Verbs (CSVs) are a set of programming functions you can use to incorporate conversion, logging, tracing, and transfer services into your applications. The Microsoft Windows CSVs represent an evolving set of CSVs that is composed of IBM Extended Services for OS/2 version 1.0 (IBM ES for OS/2 version 1.0). Additionally, a significant component of Windows CSVs is a set of Windows extensions that allow for registering and deregistering the application and that provide an asynchronous entry point for TRANSFER_MS_DATA.

Several Windows extensions are of particular importance and should be reviewed before using Windows CSVs:

  • WinAsyncCSV provides an asynchronous entry point for TRANSFER_MS_DATA only.
  • WinCSVStartup allows an application to specify the required version of Windows CSVs and to retrieve details of the specific CSV implementation.

    This function must be called by an application before issuing any further Windows CSV calls to register itself with a Windows CSV implementation.

  • WinCSVCleanup terminates and deregisters an application from a Windows CSV implementation.

    This function must be called by an application when it finishes to deregister itself from the Windows CSV implementation.

These extensions have been designed for Microsoft Windows 3.x and later versions and provide support for maximum Windows programming compatibility and optimum application performance in both 16-bit and 32-bit operating system environments. WinCSVCleanup terminates and deregisters an application from a Windows CSV implementation. WinAsyncCSV provides an asynchronous entry point for TRANSFER_MS_DATA. Finally, WinCSVStartup allows an application to specify the version of Windows CSV required and to retrieve details of the specific Windows CSV implementation.


About APPC File Transfer Protocol

The APPC File Transfer Protocol (AFTP) API is a set of C routines that provides APPC file transfer capabilities. This API makes file transfer programming easier by allowing you to access routines that will interact with any AFTP server. The AFTP API adheres to the AFTP line flow standards, which means that all AFTP client applications send the same set of line flows over a network to an AFTP server.

The following topics describe constants, conventions, and functions used in the AFTP API, and highlight those issues and techniques that are not standard to C programming. For more information about these topics, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Understanding Constants and Conventions

Microsoft SNA Server has incorporated many standard C programming conventions into the design of the SNA API. AFTP constant definitions (contained in the header file for the AFTP API) have been created for the sizes of the buffers that are passed across the SNA API. However, all buffers of the specified type must be at least the size of the defined constant to guarantee the requested call will not fail and return a buffer size error.

It is important for developers to be aware of differences between the SNA Server conventions and those common to C programming. For example, all API calls receiving strings as input require both the string itself and the length of the string. Also, the AFTP API does not require input strings to be null-terminated or guarantee that the output strings are null-terminated. The AFTP API avoids complex structures and pointers to structures for type definitions.


AFTP API Calls

AFTP API calls can be organized into the following functional categories:

  • Creating or destroying an AFTP connection object
  • Establishing and managing a connection to the AFTP server
  • Querying the characteristics of the connection to the AFTP server
  • Transferring files between the AFTP client and AFTP server programs
  • Specifying file transfer characteristics
  • Querying file transfer attributes
  • Listing files on the AFTP server
  • Listing files on the AFTP client
  • Performing directory manipulation to manage directories on the client and server
  • Performing file manipulation to modify files on the AFTP server
  • Querying system information to acquire information about the AFTP client and AFTP server computers
  • Generating message strings, which are used to get text strings for use in messages issued by your application
  • Controlling tracing of AFTP activity
  • Miscellaneous, providing a method of loading the AFTP initialization file


Common Programming Interface for Communications (CPI-C)

Microsoft® Windows® Common Programming Interface for Communications (CPI-C) was developed to provide one common API to port applications from various operating environments to Microsoft® Windows NT® and Microsoft Windows version 3.x operating systems. The CPI-C information contained in the Microsoft® SNA Server SDK represents an evolving Windows CPI-C that is composed of CPI-C version 1.2 and a set of Windows extensions that provide asynchronous call completion and support multiple application instances.

CPI-C version 1.0 was introduced to provide a mechanism for two applications to effectively communicate using the concept of conversation. A conversation is the logical connection between two programs that allows the programs to communicate with each other. Programs using CPI-C converse by making program calls. CPI-C version 1.1 was extended to include four new areas of function: support for resource recovery (not supported in Windows CPI-C), automatic parameter conversion, support for communicating with non–CPI-C programs, and local/remote transparency. Built upon CPI-C version 1.1, X/Open CPI-C provided support for nonblocking calls, the ability to accept multiple conversations, support for data conversion (beyond parameters), and support for security parameters.

CPI-C version 1.2 consolidated CPI-C version 1.1 and X/Open CPI-C by providing functionality in all the areas described above. Windows CPI-C further adds to this functionality by providing a set of extensions for asynchronous communication in addition to the full complement of supported features in CPI-C version 1.2 (with the exception of resource recovery).

CPI-C concepts are closely related to many of the concepts relevant to APPC programming and application development (for example, transaction programs and Windows extensions) and a greater understanding of CPI-C can be gleaned from these concepts. However, several development issues are unique to CPI-C. These issues are presented in the following topics.

For more information about these topics, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Important Windows CPI-C Calls

Several CPI-C calls and Windows enhancements are of particular importance to developers and should be reviewed before using Microsoft SNA Server. These calls and enhancements include:

  • Set_Processing_Mode (cmspm)
  • Specify_Windows_Handle (xchwnd)
  • Wait_For_Conversation (cmwait)
  • WinCPICCleanup
  • WinCPICExtractEvent
  • WinCPICIsBlocking
  • WinCPICSetBlockingHook
  • WinCPICSetEvent
  • WinCPICStartup
  • WinCPICUnhookBlockingHook

SNA Server generally permits one outstanding Windows SNA asynchronous call per connection and one blocking verb per thread. The exception is when an asynchronous Receive call is issued.


Asynchronous Communication

Asynchronous call completion returns the initial call immediately so the application can continue with other processes. A program that issues a call and does not regain control until the operation completes is not able to perform any other operations. To facilitate asynchronous communication, Microsoft Windows CPI-C supports the following calls and extensions:

  • Set_Processing_Mode
  • Specify_Windows_Handle
  • Wait_For_Conversation
  • WinCPICExtractEvent
  • WinCPICIsBlocking
  • WinCPICSetBlockingHook
  • WinCPICSetEvent
  • WinCPICUnhookBlockingHook

The only Windows extensions required for Windows CPI-C are for initialization (WinCPICStartup) and termination (WinCPICleanup) purposes. Depending on your application, other Windows extensions may be applicable, but not required.


Other CPI-C Development Issues for Microsoft SNA Server

There are several other operational and administrative tasks that CPI-C performs that are relevant to proper incorporation of CPI-C calls in your application. The following issues are important:

  • CPI-C maintains a set of internal values called characteristics for each conversation. Some characteristics affect the overall operation of the conversation, such as the conversation type. Others affect the behavior of specific calls, such as the receive type.
  • The information required for two CPI-C programs to communicate is stored in memory as a table, called the side information table. This table is maintained by the system administrator and contains entries for information such as the Partner LU Name and Security User ID and Password.
  • Design optimization and fulfillment of the requirements for developing applications in a Windows version 3.x, Windows NT Server, or OS/2 Client or Server environment.


3270 Emulator Interface

The Microsoft® SNA Server SDK supports the development of 3270 emulation client applications. The development of 3270 emulation clients depends on a familiarity with and understanding of SNA Server concepts and operation. Developers must also be aware of specific interface definitions used by the 3270 emulation client to communicate with SNA Server components. The following topics present these issues in greater detail.

For more information about topics not included in this overview or for a complete review of all 3270 Emulator Interface topics, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


3270 Emulator Interface Architectures and Topics

Several unique architecture concepts are contained in Microsoft SNA Server to support 3270 emulation interface clients. The BASE is a part of each SNA Server component, such as the local 2.1 node or a link service, that provides the operating environment for the core functions of that component. The BASE passes messages between components and provides functions common to all components, such as diagnostic tracing.

A BASE and the components within it (that is, an SNA Server executable program) is called a locality. The SNA Server system consists of one or more communicating localities with a single configuration file. Because the number of localities and their types are not configured in advance, the relationships among the localities are dynamically configured as individual localities come and go. Localities entering and leaving a system in this way are called dynamic localities and communicate using the DMOD (Dynamic Access Module) component.

The Microsoft SNA Server SDK pertains only to the DL-BASE, which is the type of BASE used by SNA Server 3270 emulation programs. The SNA Server DL-BASE supports a single SNA Server component or a single user application and has entry points for initialization, sending messages, receiving messages, and termination.

Microsoft SNA Server supports the concept of identifiable partners within a locality to facilitate components and applications communication. The term partner refers to an addressable component of a locality—that is, code to which messages can be sent. In an SNA Server system, there is generally only one partner within a locality (such as a link service or the 3270 emulation program); however, separate functions within the local 2.1 node (such as the 3270 or APPC functions) may be considered separate partners.

The content of the communication between components and applications in a Microsoft SNA Server environment is called a message. Messages always contain fixed-format header information, such as a message type and addressing information and, generally, other header information specific to a particular message type (other data can be included also).

Messages are saved in buffers. The buffers consist of the following members:

  • Header, which contains the fixed format information and a pointer to an element.
  • Element, which contains any extra data for a message and a pointer to another element (this member is not required).

A message is composed of a buffer header, and elements of contiguous (8-bit) byte sequences of any length, chained to the header. Partners communicate by establishing an LPI connection, and then passing messages to each other (each identified by an LPI address).


DL-BASE/DMOD Interface

The Microsoft SNA Server DL-BASE/DMOD Interface includes significant entry points that an application, such as a 3270 emulator, can call to send and receive messages from services such as the local 2.1 node.

Several important tasks occur during proper DL-BASE/DMOD Interface operation:

  • The 3270 emulator initializes the DL-BASE and then calls the Dynamic Access Module (DMOD) to obtain the necessary configuration information (this also registers the user name with the DMOD). If required, it can obtain further system information such as the SNA Server version number.
  • The 3270 emulator inserts the message in a buffer and then calls the DL-BASE to send it. The message contains Source and Destination LPIs, which are set up when the connection is opened.
  • When the DMOD receives a message, it calls the 3270 emulator routing procedure (registered during DMOD initialization), which then processes the message.
  • LPI connections are opened before data is transferred.
  • The 3270 emulator must call SBPUTERM to free DL-BASE/DMOD resources before it terminates.

Task switching, supported by MS-DOS version 5.0 and later as well as by Windows operating systems, is handled by the DMOD, and need not concern the 3270 emulator developer. However, the DMOD provides a means, using the REGISTERSWITCHPROC call, for the application to make use of the task switch detection.

The MS-DOS–based client Network Access Protocol (NAP) provides full support for applications that allow switching between foreground and background operation (for example, terminate-and-stay-resident applications), including fully preemptive scheduling of a background thread. To avoid possible interaction problems, it is important that client applications that will support background operation make use of the facilities provided by the NAP (such as the scheduler and semaphores), rather than implementing separate scheduling mechanisms hooked from MS-DOS interrupts.


Function Management Interface

The Function Management Interface (FMI) provides applications with direct access to SNA data flows and information about SNA control flows by means of status messages, while shielding the application from the full complexities of SNA protocol handling. FMI is particularly suited to the requirements of applications emulating 3270-type controllers. The FMI is defined in terms of the messages that are sent across the interface. This is logically distinct from the definition of the DL-BASE/DMOD interface, which defines the mechanism for sending messages between two components in Microsoft SNA Server.

The FMI is used by logical unit (LU) types 0, 1, 2, and 3, but not by LU type 6.2. It provides access to the system service control point logical unit (SSCP-LU) session as well as the main primary LU-secondary LU (PLU-SLU) session. An application can use the FMI to access multiple sessions, and hence multiple LUs, simultaneously. The 3270 emulator on the client communicates over the LAN with the local node on the server computer by exchanging messages. The content and format of the messages are defined by the FMI.

An application using the FMI can communicate on three SNA sessions:

  • The SSCP session, which defines access between the SNA Server secondary LU and the host SSCP.
  • The PLU session, which defines access between the SNA Server LU and a PLU (primary LU) in the host.
  • The PU-SSCP session which defines access between the physical unit (local node) and the host SSCP.

Developers should be aware of other important FMI issues, such as protocol structure and status messages.


Microsoft SNA Server Diagnostics

Microsoft SNA Server provides several diagnostic mechanisms to use in 3270 emulator client application development. SNA Server provides one message file that you can use for error and audit logging. Your application can write error and audit log messages to SNA Server log files. SNA Server has one message file that is used for all its error and audit logging. In addition, SNA Server provides internal tracing macros that can be used to check the operation of the application during development. The COM_TRC_HLLAPI macro can be used within an HLLAPI library to trace the parameters supplied to an HLLAPI function as well as the returned values. Finally, SNA Server supports the facility for tracing message flows at the Function Management Interface (FMI), both at the local node and at the application's DL-BASE.

For detailed information about SNA Server diagnostic techniques and capabilities, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


Logical Unit Application Programming Interface

The conventional Logical Unit Application (LUA) programming interface is an API that allows you to write logical unit applications to communicate with host applications. The interface is provided at the request/response unit (RU) and session levels, allowing programmable control over the Systems Network Architecture (SNA) messages sent between your communications software and the host. It can be used to communicate with any of the logical unit (LU) types 0, 1, 2, or 3 at the host; it is up to the application you develop to send the appropriate SNA messages required by the host.

The Microsoft® SNA Server 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® graphical environment, and the IBM Extended Services for OS/2 version 1.0 (IBM ES for OS/2 version 1.0) operating system.

The following topics provide a conceptual overview of LUA and discuss important programming considerations. For more information about these topics, see the Microsoft SNA Server documentation in the "Internet, Networking, and Distributed Services" section of the Microsoft Platform SDK.


LUA Concepts

The Windows LUA for Microsoft SNA Server provides one common API to port applications from various operating environments to Microsoft Windows NT and Windows version 3.x. The LUA verbs (both Request Unit Interface [RUI] and Session Level Interface [SLI]), routines, and information contained in the Microsoft SNA Server SDK represent an evolving Windows LUA that is based on IBM ES for OS/2 version 1.0. The SDK also includes a set of Windows enhancements for application development.

An application accesses the LUA through either the RUI or SLI verbs and routines. Each verb, defined by a structure called the verb control block (VCB), supplies parameters to the LUA, which performs the desired function and returns parameters to the application.

By design, the LUA is asynchronous and uses semaphores for notification messages. While semaphores work extremely well for the Windows NT and OS/2 systems, the Windows enhancements built into the Windows LUA also allow for asynchronous support for Windows version 3.x-based applications in the LUA interface. The Windows LUA provides the following entry points for both RUI and SLI verbs: RUI, SLI, WinRUI, and WinSLI. WinRUI and WinSLI provide asynchronous message notification for all Windows-based RUI and SLI verbs, while RUI and SLI provide support for event notification. Windows 3.x-based applications use WinRUI and WinSLI for asynchronous message notification.

The only Windows extensions required for the Windows LUA are for initialization (WinRUIStartup or WinSLIStartup) and termination (WinRUICleanup or WinSLICleanup) purposes. Depending on your application, other Windows extensions may be useful to you, but are not required.

Several LUA calls and Windows enhancements are of particular importance and should be reviewed before using Microsoft SNA Server:

  • WinRUI/WinSLI, which provide asynchronous notification for all Windows-based RUI and SLI verbs.
  • WinRUIStartup/WinSLIStartup, which allow an application to specify the version of the Windows LUA required and to retrieve details about the specific LUA implementation.
  • WinRUICleanup/WinSLICleanup, which terminate and deregister an application from a Windows LUA implementation.
  • RUI/SLI, which provide event notification for all RUI and SLI verbs.


Programming Considerations

Many of the programming techniques used in developing LUAs are similar to those used to write APPC applications. The following issues are important to LUA programming:

  • Windows extensions, such as WinRUI and WinRUICleanup, and the GetLuaReturnCode function are important to efficient use of the LUA and should be used along with other Windows extensions and enhancements when possible.
  • Specific tasks may be necessary when developing applications for the Windows NT, Windows 95, Windows version 3.x, MS-DOS, or OS/2 system.
  • Several important programming techniques should be incorporated into your application such as using multiple processes and sessions, properly using an LUA LU pool, as well as specific tasks such as BIND checking, distinguishing SNA sense codes from other secondary return codes, and purging the remaining data upon receipt of a negative response.


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.