═══ Unformatted Text ═══ ═══ 1. Notices ═══ References in this publication to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any of IBM's intellectual property rights or other legally protectable rights may be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility. IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you any rights to these patents. You can inquire, in writing, to the IBM Director of Licensing Services, IBM Corporation, 500 Columbus Avenue, Thornwood, NY 10594 - U.S.A. ═══ 1.1. Trademarks ═══ The following terms in this publication are trademarks of the IBM Corporation in the United States, other countries, or both: AIX AIX/6000 AIX RISC System/6000 AnyNet CICS Communications Manager/2 DataGlance DATABASE 2 OS/2 DATABASE 2 RISC System/6000 DB2/2 DB2/6000 Distributed System Object Model DSOM FFST/2 First Failure Support Technology/2 IBM LAN Distance LAN Server MPTS Multi-Protocol Transport Services MVS NetDoor NetSP Network Transport Services/2 NTS/2 Operating System/2 Operating System/400 OS/2 OS/400 Person to Person/2 PowerPC Presentation Manager RISC System/6000 SAA SNA SPM/2 Systems Application Architecture Systems Network Architecture System Performance Manager/2 Ultimedia The following terms in this publication are trademarks of other companies as follows: ATT American Telephone Telegraph cc:Mail cc:Mail, Inc. Encina Transarc Corporation HP Hewlett-Packard Company Intel Intel Corporation Macintosh Apple Computer, Inc. NetWare Novell, Inc. Lotus Notes Lotus Development Corporation OpenDoc Apple Computer, Inc. Open Software Foundation Open Software Foundation, Inc. OSF Open Software Foundation, Inc. PostScript Adobe Systems, Inc. Taligent Taligent, Inc. UNIX Unix System Laboratories, Inc. UnixWare UNIX System Laboratories, Inc. Windows Microsoft Corporation X/Open X/Open Company ═══ 2. What This Roadmap Covers ═══ IBM LAN Systems products provide file and print serving, distributed computing, and distributed objects, across multiple operating systems including OS/2, AIX, DOS, OS/400 and Windows. Current products include: o LAN Server o LAN Server for Macintosh o LAN Server for Ultimedia o LAN Server/AIX o LAN Server/400 o LAN Server for VM or MVS o LAN Distance o AnyNet o Distributed Computing Environment o Encina o NetView family of products o SOMobjects The LAN Systems family of products provide APIs for a wide range of operating system environments that span the entire range of functions required for robust, client/server programming support. Hundreds of APIs are available for application development, but a given application may only need a few. To make it easier to determine the APIs that benefit you and your application, this document uses the Open Blueprint concepts to categorize the APIs. This document also outlines IBM's vision for a client/server application development environment based on an integrated distributed computing platform. As this document evolves with each quarterly release of the Developer Connection, further details of the application interface strategy for each functional category, including information on the industry standard APIs provided for application portability across hardware platforms, as well as object frameworks, will be provided to assist you with reusing code. Hints: o See the sections marked Future Directions or Hints to discover the 'application programming roads' that are available now or under construction, the sights to see along the way, and the roadblocks to avoid. o See the LAN Systems API Implementation Guidelines on the Developer Connection for LAN Systems CD for detailed instructions on the best route to take advantage of the LAN as a system when designing applications. o For a technical description of the Open Blueprint, refer to the IBM Open Blueprint: Technical Overview Open Blueprint: Technical Overview , GC23-3808-00. o For a more comprehensive tour of the IBM products dedicated to getting you on the fast track to client/server development, refer to the Client/Server Survival Guide by Orfali and Harkey, available from Van Nostrand Reinhold publishers. ═══ 2.1. What is a LAN System? ═══ The personal computer has enhanced the way people communicate and the way in which they work. Originally, local area networks (LANs) provided a way for a group of people who were located together to share resources and communicate. As PC's became faster and their capacity grew, new applications capitalized on the LAN's communications capabilities, that were also becoming faster and more capable. People wanted applications that could send mail, share files, access centralized databases, and use expensive output devices. Communication is now with people both down the hall and around the world. Technology now enables LAN systems to meet any geographic requirement and can support computers attached remotely or only occasionally, for mobile computers. The LAN system of today encompasses different operating systems, a wide variety of applications, sophisticated communications, and large numbers of users. It requires the management, administration, and reliability that are appropriate for this sophistication and complexity. The strategy for IBM LAN systems is to simplify these complex environments from the application developer's perspective by treating the LAN as a system. This manageable LAN environment serves as the platform for a new generation of distributed applications. Backing up this strategy is IBM's commitment to adhere to an Open Blueprint that addresses the challenges of the distributed computing environment. This approach enables the development, execution, and management of distributed, client/server applications work together in an integrated fashion in today's heterogeneous, multivendor environment. Today's IBM LAN systems products are designed to provide a single system image of the network, giving users access to the information they need, regardless of where that information is located. At the same time, the products insulate application developers and administrators from the complexities of the network: including connections, protocols, service providers, and hardware. o From a user's perspective, this means that the user logs in once and accesses resources anywhere in the network (given the appropriate authorization) without needing to know where a given resource resides. The resources in the network are represented as seamless extensions to their local resources and are manipulated the same way. o From an administrator's perspective, administrative tasks within the network can be performed by modifying the contents of the distributed directory or security servers rather than administering the user and resource on each server separately. In addition, administration can be performed from anywhere in the network. o From an application developer's perspective, the same programming interfaces are available from anywhere in the network to enable application portability among heterogeneous machines. ═══ 2.2. LAN Systems API Strategy ═══ The LAN Systems API Strategy has three main elements: 1. The full set of APIs necessary to write distributed client/server applications will exist on every platform. 2. The use of an API is independent of selecting its implementation at run time. 3. The evolution of APIs to exploit the parts concept. Support will continue for key procedural APIs that are available from IBM today. Strategic APIs available today are: VIM Mail LAKES API Collaboration OpenDoc Compound Document TransC, CICS Transaction Processing OSF/DCE RPC Remote Procedure Calls Sockets Sockets CPI-C Conversation MQI Messaging OSF/DCE security and XDS Distributed System Services SOM Object Services PM GUI MMPM/2 Multimedia DMI Configuration, Installation and Distribution netls Licensing IBM will provide object oriented frameworks to access distributed services such as directory, transaction, user registry, time, authorization, and authentication. These frameworks are sets of class libraries defined with IBM SOM. Exploiting the strengths of SOM, it will be possible to write client/server applications in a range of languages including C, C++, Smalltalk, REXX, and Object COBOL. Note: It is possible to write applications that use procedural APIs, either alone or in conjunction with related object oriented frameworks. ═══ 2.2.1. The Integrated Distributed Computing Platform ═══ The goal is to make all of the APIs that enable writing clients and servers available on OS/2. Thus, the application being executed is independent of whether the computer is dedicated to a single user or is serving multiple users simultaneously. The blurring of the distinction between client and server allows application developers and customers to make decisions on security, recovery, performance, and resource requirements without having to retarget the application to specific APIs. This will allow client/server applications to be developed on a single workstation with a set of development tools that support design, prototype, implementation and test. Once developed and tested, the application parts can be targeted to specific client and server platforms. ═══ 2.2.2. API Independence ═══ The independence of an API from implementation is the key to portability and interoperability in distributed client/server systems. Already communication APIs allow multiple transport protocols to be used between client and server. The strategy continues this to higher layers of function in areas such as database access, document management, mail, and distributed services. The application developer selects APIs and the customer can decide which product will provide its corresponding function. The implementation technique for providing this capability is generally called a framework. A framework has two interfaces defined: an application programming interface (API) and a service provider interface (SPI). The implementation is called through the SPI based on information passed in the API or discovered from the configuration. When the concept is extended to object oriented programming, a framework is a set of related classes, embodying a design, that programmers can use, extend, or customize for specific computing solutions. Refer to the Taligent Glossary, Building Object-oriented Frameworks White Paper, 1994 for more information. The evolution of programming technology adds another dimension to the API strategy. In a well-designed system, the API is the doorway through which requests for service are passed and results are returned. It is important to ensure that programs respect the side of the door they are on. It is also key that the system have the right number and type of doors. In object technology, there is support in the programming languages and SOM to enable the separation of responsibilities and to create the right number of doors to function. The API strategy will take advantage of this evolution by having a spectrum of APIs for groups of function. Today's calls to DLLs and system functions will be supplemented by class implementations for the function. The first step is to create classes provide the equivalent function of today's APIs and support OO programming. The second step organizes these classes into frameworks. This second step is quite complex for system designers, because all of the classes need to follow a common architecture and behave in the same way. We don't believe that every procedural API maps one-to-one to an object interface nor that every object class needs a corresponding function implemented with a procedural API. The exploitation of objects will make it easier to use system and service functions so we expect the volume of APIs to be reduced within functional areas. Refer to the Taligent white papers on the Developer Connection for OS/2 for more insight into this area. ═══ 2.2.3. Exploiting Parts ═══ The API evolution has a third step as well. Visual application building tools exploit the concept called parts. A part is a self-contained unit of function that supports particular behaviors. The behaviors are both the purpose for which the part was created (e.g. display text information) and the responsibilities of the part within the whole (i.e. a compound document). These responsibilities typically include handling events from the user interface, being scriptable, storing its data in containers, and others. Use of this concept is very natural for people who want to assemble applications that meet their needs. It is an object concept which does not require everything to be programmed with object languages. From an application developer's viewpoint, the building of parts offers the best opportunity to create useful, modern, and powerful solutions to problems when the infrastructure exists to support their build and use. Products like VisualAge and the forthcoming OpenDoc from CI Labs are for this purpose. The API evolution is related in the following example. The procedural APIs for simple mail allow an application to use the mail system for sending and receiving simple messages. An object implementation provides method calls to an mail object. The definition of a Mail class evolves into a mail framework, that provides objects for determining addresses of mail recipients, saving messages, filtering them, etc. The usefulness of the framework is its ability to allow different implementations of the classes, for example, mail objects might be stored in files, databases, remotely, based on the customer's need. The mail part allows application developers (and end users given the power of new tools) to use Mail as an application building block. The application might be tax processing where delinquent notices are generated automatically. From your perspective, the function provided by the mail API becomes richer. This richness pays off in better applications. The mail API accepted a string and a user name and sent a message. A mailbox object can accept documents, drawings, and video-clips and send them. The mailbox framework does the this, but can also resolve user name in a global directory and then choose a mail protocol based on the type of object being sent and the destination. The mail part allows a developer or end user to use mail as a building block, for example, when constructing a workflow solution. The goal is to allow the application developer to create functional parts that reflect a unique knowledge of the problem being solved and then knit these to parts developed by others. Parts that look up things in directories, send things around networks, and manage resources will be provided with the distributed client/server system. Of course, the entire scenario above could have been done with procedural APIs and 3GL or 4GL programming (and for the most part has been). We believe that the use of object technology, supported as part of the operating system and its servers, significantly increases your ability to create and exploit the capabilities that application developers and end users need. ═══ 2.2.4. More About DCE and LAN Server ═══ LAN Server and DCE define a set of complementary, and in some cases overlapping services. Today, IBM delivers both DCE and LAN Server on a set of platforms and they can coexist on those platforms, but there is no integration of the two. In future releases, LAN Server will integrate DCE core services, supplementing the LAN Server functionality with features such as RPC, and replacing directory and security services with the more scalable, flexible, and open services provided by DCE. A set of automatic migration functions, interoperability gateways, and synchronization daemons provide a smooth path from LAN Server 3.0 and 4.0 to this new environment, preserving interoperability with clients and servers of these environments and the clients and servers from other SMB based networks including Microsoft's Windows for Workgroups and NT. o The Evolution o Hints ═══ 2.2.4.1. The Evolution ═══ Future versions of LAN Server will preserve LAN Server programming interfaces, adding the complementary APIs of DCE and mapping existing LAN Server APIs onto corresponding DCE APIs where LAN Server services are replaced by DCE-based services, so that existing LAN Server exploitive applications will continue to run in the integrated environment and new applications can take advantage of all the features of the combined programming environment. To describe how the current LAN Server programming interfaces will be preserved, it is important to understand a set of categories of workstations that the LAN Server environment will include: o Legacy clients and servers (LAN Server 3.0 and 4.0) o Unintegrated clients and servers (clients and servers with updated LAN Server code, but not using the DCE core services) o Pure DCE clients and servers (clients and servers running DCE from IBM or other vendors that do not run LAN Server) o Integrated clients and servers (clients and servers running updated LAN Server code with the DCE core services) The general model for preserving the LAN Server programming interfaces is as follows: For legacy and unintegrated clients, which do not have the DCE APIs locally, mapping from the LAN Server APIs onto DCE APIs is performed at the server (usually the domain controller). The domain controller acts as a gateway to the Cell Directory Service (CDS) and Cell Registry. Pure DCE clients administer the information in the Cell Directory Service and DCE Registry directly, using the DCE APIs. Applications on integrated clients can use either the DCE APIs directly or they can continue to use the LAN Server APIs. In the latter case, the LAN Server APIs are mapped onto DCE APIs at the client, so that the client interacts directly with the DCE Services without the need for a LAN Server domain controller to act as a gateway. ═══ 2.2.4.2. Hints ═══ o LAN Server Version 4.0 provides several functional upgrades to Version 3.0; the most significant to programming is the support for both 16-bit and 32-bit applications. Support for both types of applications allows a gradual change of LAN Server APIs into 32-bit worker routines without requiring 32-bit applications to change. The availability of 32-bit APIs in LAN Server 4.0 raises the interface one layer. In Version 3.0, the programmer had to do much of the work of thunking pointers in data structures. The new 32-bit APIs eliminate that work. This document only specifies the 32-bit APIs. For more information about 32-bit and 16-bit APIs, see the LAN Server Programming Guide and Reference. o This document identifies several DCE APIs that are available with OSF DCE 1.1. These APIs will soon be available from IBM; look for them on future versions of the Developer Connection for LAN Systems. o Over time the LAN Server APIs will be de-emphasized in favor of the open APIs endorsed by OSF, OMG, X/Open and other distributed computing standards bodies. In many cases, these interfaces will be implemented as procedural or object frameworks, allowing for a range of service providers to be incorporated into the environment, transparent to applications using the programming interfaces. LAN Server APIs will be gradually phased out in favor of these open interfaces, but mapping layers will be provided for important APIs to allow for a smooth, gradual migration and port of existing applications. ═══ 2.2.5. More about Objects ═══ Today, the IBM runtime architecture for object-oriented application development includes an object model, object services, object-oriented application frameworks, a part (or compound document) programming model, and customizable desktops. A set of tools accompany this enabling software that includes integrated development environments, visual application builders, and both compiled and interpreted programming languages. o Object Enabling - SOM and DSOM o Basic Object Services - SOM Toolkit Frameworks o Application Frameworks - C/Set++ and Taligent o Part Enablement - OpenDoc/OSA o Customizable Desktops o Tools ═══ 2.2.5.1. Object Enabling - SOM and DSOM ═══ The system object model (SOM) provides the foundation for all IBM runtime object services. SOM provides two key features for application development: o Compiler and language independence by allowing classes to be defined in one language and then implemented, used or subclassed from another language. o Binary code reuse and permits class libraries to be enhanced without requiring existing applications to be recompiled from source code. SOM conforms to the Object Management Group object model architecture and its common object request broker architecture (CORBA) specification. Application developers can use OMG IDL interface specification language with IBM precompilers to implement SOM objects in C, C++, or COBOL programming languages today. Vendors are presently working with IBM to produce SOM language bindings for SmallTalk. Scripting languages can also be supported, such as Object REXX or Object BASIC. With certain compilers, C++ definitions can replace IDL. Distributed SOM (DSOM) supplies the infrastructure to support distribution of SOM objects across a heterogeneous network. Among other things, this infrastructure provides local-remote transparency for binary objects. A class or a framework can be developed and compiled in a single address space without object distribution and then later can be deployed as distributed binary objects. DSOM complies with the OMG CORBA specification. CORBA mandates interface and implementation repositories, a basic object adapter, an object request broker for object location and activation, and both static and dynamic method invocation. DSOM goes beyond the CORBA specification through the use of proxies rather than simple RPC stubs in the calling process. When an object is remote from the caller, a proxy object is used to forward requests to the remote object. The proxy provides the same interface as the remote object, and the caller need not be aware that it is communicating with a remote object. DSOM generates default proxies automatically, but developers can also create specialized proxies that take advantage of such techniques as caching and local computation. ═══ 2.2.5.2. Basic Object Services - SOM Toolkit Frameworks ═══ IBM implements OMG services as flexible, extendible object frameworks. Since the OMG specification is minimal, IBM extends these services in the frameworks to provide complete distributed application function. For example, IBM's persistent object framework supports both single-level, implicit object storage and explicit save/restore management of persistent objects. In addition, the IBM persistent object framework can support various storage mechanisms, including file storage, relational database storage, and object database storage. Providing data store independence is a key goal of the IBM persistence and transaction frameworks. The IBM object service frameworks allow developers to incrementally add service function to any SOM object without any unique design. Class developers write their code without concern for normal system-like services (for example, persistence, concurrency, recover ability, security, or distribution). The user of the class then specifies the combination of services that are desired in a particular instantiated object. SOM binary run-time mechanisms, such as runtime subclassing and before/after metaclasses, then provide those desired features. Object services currently available in the SOM Toolkit include collection classes, persistence, and replication. The OMG first-object service specifications were adopted after the SOM Toolkit release, but IBM plans to enhance the SOM Toolkit object services to meet the OMG specifications. These will include event notification, enhanced persistence, lifecycle, naming, externalization, transactions, concurrency, relationships, and security. ═══ 2.2.5.3. Application Frameworks - C/Set++ and Taligent ═══ IBM provides a set of cross-platform application frameworks to improve the productivity of C++ programmers. Today, these ship with C/Set++ for AIX and OS/2. These frameworks will soon be significantly enhanced with technology from the Taligent object-oriented application environment. The IBM application frameworks today cover portable classes, collections, user interfaces, string handling, and some operating system functions such as threads. In the future, IBM will add database access, graphics, conversational communications, internationalized text, printing, more operating system classes, and a compound document framework. These will be available in a choice of two C++ toolkits: a "Starter Set" supports smaller machines and today's user interface, while a "Complete Set" supports the complete Taligent application environment, user interface and programming model. ═══ 2.2.5.4. Part Enablement - OpenDoc/OSA ═══ OpenDoc is software that enables a compound document, or part, programming model. The OpenDoc protocol allows applications from multiple vendors to be broken down into small task-specific parts. These parts from can then be combined in many ways by either end users or script programmers to create application solutions. Parts are generally presented as pieces of a compound document. OpenDoc is a product of CILabs, an open consortium of vendors including Apple, IBM, WordPerfect, and Lotus. OpenDoc specifies protocols to vendors to produce interoperable compound document parts. These protocols are specified in IDL, and CILabs provides implementations based on SOM/DSOM, using C++ bindings. OpenDoc supports Microsoft OLE II parts in its implementation on Windows. This means parts written to either OLE II or OpenDoc can interoperate within the same document. The IBM application frameworks described previously support OpenDoc part protocols. Creating parts with these frameworks is considerably easier than creating parts by coding directly to the OpenDoc interface. OpenDoc provides scripting using the Open Scripting Architecture. Any OSA-compliant scripting language can use an OpenDoc part. Programmers can rapidly assemble parts into more complex parts and applications using these scripting languages. IBM plans to give end-users and non-professional programmers visual development environments that allow parts to be connected into more complex parts or complete applications, using direct manipulation and scripting languages such as Object Basic or Object REXX. ═══ 2.2.5.5. Customizable Desktops ═══ The part programming model and the IBM framework implementation provides an excellent base on which to support customizable and extensible desktops. This is a future direction of IBM that builds on Taligent's desktop technology, their "People, Places and Things" metaphor, and existing desktop models for OS/2 and AIX. ═══ 2.2.5.6. Tools ═══ IBM provides cross-platform tools for both C++ and SOM IDL object development. Platforms supported include AIX, OS/2, Windows (partial), and Solaris (partial). Tools such as compiler, linker, debugger, browser, performance analyzer, and configuration manager are combined into an integrated development environment for professional programmers. IBM is adding a visual application builder to assist programmers in creating parts and user interfaces. Tools are also being added to aid in understanding complex object frameworks and to aid in search and retrieval of classes and frameworks that can be reused to meet the specified criteria. The Taligent development environment (TalDE) will be a rapid prototyping environment for users of the IBM application frameworks. In particular, TalDE will support incremental compiles as well as fast search and retrieval of appropriate framework code for desired uses. For non-professional programmers and end users, IBM is creating visual development environments that require almost no coding. The small amounts of code that are required can be written quickly with SOM-enabled, OSA-compliant scripting languages. ═══ 3. Contents of The Developer Connection for LAN Systems ═══ The Developer Connection for LAN Systems CD-ROM is a cross-platform offering that supports the installation of products and information for OS/2, Windows, DOS, and AIX workstations. It provides the programming environment required for client/server and distributed computing application development. This section is divided into the following sections: o The Developer Connection Catalog o Books in the Developer Connection Browser o BookManager Books o PostScript Books ═══ 3.1. The Developer Connection Catalog ═══ The Developer Connection for LAN Systems contains a number of products that can be installed onto your network. See the following sections for a listing of the available products. o LAN Systems Toolkits o Product Overviews o LAN Systems Tools o Sample Code o Service ═══ 3.1.1. LAN Systems Toolkits ═══ The Developer Connection for LAN Systems includes the following toolkits: o OS/2 LAN Server 4.0 APIs LAN Distance APIs Sockets APIs Network SignON Coordinator API User Profile Management APIs DCE Application Enabler for OS/2 SOMobjects Workgroup Enabler Toolkit 2.1 SNMP DPI Version 2.0 Note: For additional information about these toolkits, open the Developer Connection Catalog and LAN Systems Toolkits icons. Then open the icon for the product you want to learn more about and click on the Extended Description button. o AIX DCE Toolkit Encina Toolkit MakeDCE DCE Password DCESTAT XCell Profiler EZDCE PDDA6000 SMT Note: For additional information about the AIX development tools, see the AIXREAD.ME file on the \AIX directory of the Developer Connection for LAN Systems CD-ROM. ═══ 3.1.2. Product Overviews ═══ The Developer Connection for LAN Systems includes the following product overviews: DatagLANce (Evaluation) DCE (Illustration) LAN Distance (Evaluation) LAN Server 4.0 (Evaluation) NetDoor (Evaluation) NetFinity (Evaluation) Person to Person/2 (Evaluation) AnyNet for OS/2 (Evaluation) AnyNet SNA over TCP/IP (Evaluation) NetView Distribution Manager/2 (Evaluation) For additional information about the product overviews, open the Developer Connection Catalog and Product Overviews icons. Then open the icon for the product you want to learn more about and click on the Extended Description button. ═══ 3.1.3. LAN Systems Tools ═══ The Developer Connection for LAN Systems includes the following LAN Systems tools: DirStat LANXCopy MakeDCE Library Read/2 RINGUTIL GENE/D LAN Server REXX Utility LAN Server Specialist NetWare to LAN Server Migration Tool LAN Manager to LAN Server Migration Tool For additional information about the LAN Systems Tools, open the Developer Connection Catalog and LAN Systems Tools icons. Then open the icon for the product you want to learn more about and click on the Extended Description button. ═══ 3.1.4. Sample Code ═══ Sample code may be included with specific products in the LAN Systems Toolkit. For more information, see the LAN Systems API Toolkit document in the Technical References section. Redbook Sample Code: 3.5" Diskettes For additional information about the sample code, open the Developer Connection Catalog and Sample Code icons. Then open the Redbook Sample Code icon and click on the Extended Description button. ═══ 3.1.5. Service ═══ The Developer Connection for LAN Systems includes the following service offerings: LAN Distance Service Pak LAN Server 3.0 Service Pak DOS LAN Support Program Service Pak OS/2 NTS/2 Service Pak AnyNet Service For additional information about the service offerings, open the Developer Connection Catalog and LAN Systems Tools icons. Then open the LAN Systems ServicePaks icon and click on the Extended Description button. ═══ 3.2. Books in the Developer Connection Browser ═══ The following references can be accessed online. Open the Developer Connection for LAN Systems icon and select The Developer Connection Browser. The online books are contained in the following folders: o Multiple-Protocol Transport Services Books o Customization, Installation, Distribution (CID) Books o LAN Server 4.0 Books o DCE Application Enabler Books o AnyNet/2 Books o NetView DM/2 Books o LAN Systems Information o Red Books o Technical References o White Papers ═══ 3.2.1. Multiple-Protocol Transport Services (MPTS) Books ═══ The following online books are in the MPTS Books folder: Multi-Protocol Transport Services - AnyNet for OS/2: Configuration Guide Multi-Protocol Transport Services - AnyNet for OS/2: Error Messages and Problem Determination Guide Multi-Protocol Transport Services - AnyNet for OS/2: Programmer's Reference ═══ 3.2.2. Customization, Installation, Distribution (CID) Books ═══ The following online books are in the Customization, Installation, Distribution (CID) Books folder: CID-Enabled Applications CID Enablement Guidelines LAN Configuration, Installation, and Distribution Utility Guide ═══ 3.2.3. LAN Server 4.0 Books ═══ The following online books are in the LAN Server 4.0 Books folder: LAN Server 4.0 Commands and Utilities LAN Server 4.0 DOS LAN Services and Window's User Guide LAN Server 4.0 LAN Requester User's Guide LAN Server 4.0 Network Administrator's Reference Vol. 1: Planning, Installation, and Configuration LAN Server 4.0 Network Administrator's Reference Vol. 2: Performance Tuning LAN Server 4.0 Network Administrator's Reference Vol. 3: Network Administrator Tasks LAN Server 4.0 Problem Determination Guide LAN Server 4.0 Programming Guide and Reference Network SignON Coordinator User's Guide ═══ 3.2.4. DCE Application Enabler Books ═══ The DCE Application Enabler Books can be viewed only with the IBM Library Read/2 book viewer. If you already have the viewer installed, you can access the following books directly from the DCE Application Enabler Books folder. For information about how to install BookManager, see the BookManager Books section. IBM DCE Application Enabler for OS/2 Application Development Guide (A3U1XMST) IBM DCE Application Enabler for OS/2 Getting Started (A3U1YMST) IBM DCE Application Enabler for OS/2 Administration Guide and Reference (A3U20MST) IBM DCE Application Enabler for OS/2 Application Development Reference (A3U21MST) ═══ 3.2.5. AnyNet/2 Books ═══ The AnyNet/2 Books can be viewed only with the IBM Library Read/2 book viewer. If you already have the viewer installed, you can access the following books directly from the AnyNet/2 Books folder. For information about how to install BookManager, see the BookManager Books section in this document. AnyNet/2 Version 2.0 SNA over TCP/IP (IPMC0MST) AnyNet/2 Version 2.0 Sockets over SNA (IPNCOMST) AnyNet/2 Sockets over SNA Gateway Version 1.1 (IPLC1MST) AnyNet/2 IPX for SNA Gateway Version 1.1 ═══ 3.2.6. NetView DM/2 Books ═══ The NetView DM/2 Books can be viewed only with the IBM Library Read/2 book viewer. If you already have the viewer installed, you can access the following books directly from the AnyNet/2 Books folder. For information about how to install BookManager, see the BookManager Books section in this document. NetView DM/2 Quick Help for DOS/Windows ═══ 3.2.7. LAN Systems Information ═══ The following online documents are in the LAN Systems Information folder : Client/Server Survival Guide (excerpts) LAN Server REXX Utility Readme LAN Server System Builders Product List LAN Software Buyer's Guide LAN Systems API Implentation Guidelines LAN Systems API Roadmap LAN Systems News Ready! for IBM LAN Tested and Approved for IBM LAN LAN Systems CSD Newsletter SOMobjects README ═══ 3.2.8. Red Books ═══ The Red Books can be viewed only with the IBM Library Read/2 book viewer. If you already have the viewer installed, you can access the following books directly from the Red Books folder. For information about how to install BookManager, see the BookManager Books section. Experiences with the IBM OS/2 LAN Server Version 3.0 New Functions (GG243959) The IBM OS/2 LAN Server Version 3.0 System Recovery Considerations (GG244043) Developing DCE Applications for AIX, OS/2, and Windows (GG244090) OSF DCE for AIX, OS/2, and DOS Windows Overview (GG244144) IBM LAN Distance Configuration and Customization Guide (GG244158) Understanding IBM OS/2 LAN Server Ultimedia Version 1.0 (GG244224) SOMobjects: A Practical Introduction to SOM and DSOM (GG244357) Migrating to LAN Server from NetWare (GG244388) ═══ 3.2.9. Technical References ═══ The following online books are in the Technical References folder: LAN Systems: DCE Concepts DatagLANce User's Guide DCE Concepts LAN Systems API Toolkit MakeDCE - DCE Application Developer Tools User's Guide IBM Advanced NDIS (ANDIS) IBM LAN Distance Advanced Guide IBM LAN Distance Dial Services Interface Programming Guide IBM LAN Distance Remote Guide IBM LAN Server REXX Utility DLL MakeDCE User's Guide LAN Technical Reference: IEEE 802.2 and NetBIOS APIs (AFA0CNTL) ═══ 3.2.10. White Papers ═══ The following online documents are in the White Papers folder: Distributed Performance of IBM DCE for OS/2 IBM DCE Client for Windows Performance IBM DCE for OS/2: Key Function Performance IBM DCE Heterogeneous Enterprise Performance IBM Network Door/2 IBM OS/2 DCE: Multiuser Application Performance LAN Server Ultimedia Memory Leaks Top Tips for LAN Server 3.0 Before/After Metaclasses in SOM IBM's System Object Model (SOM) LAN Server 4.0 Performance LAN Server for AIX SOM and COM Compared SOM and COM Developer's Perspective ═══ 3.3. BookManager Books ═══ Many of the books stored on the Developer Connection for LAN Systems are available in softcopy BookManager format. These books can be viewed only with the IBM Library Read/2 book viewer. If you do not already have the viewer installed, it is on the Developer Connection for LAN Systems under LAN Systems Tools. During installation, you must specify the boot drive as the install directory in order to open books directly from The Developer Connection Browser. ═══ 3.4. PostScript Books ═══ The following technical references are available in PostScript format. o Encina for AIX The following books are available for you to print after you install one of the AIX development tools. Encina Application Development Guide Encina Base Reference Encina Server Reference Encina Transactional-C Programmer's Guide and Reference Encina Server Administration: Programmer's Guide and Reference Encina PPC Executive Programmer's Reference Encina SFS Programmer's Guide and Reference Encina Monitor Programmer's Guide and Reference MakeDCE User's Guide AIX DCE Application Development Guide AIX DCE Application Development Reference o SOMobjects Toolkit Publications The following books are available for you to print after you install the SOMobjects Toolkit. SOMobjects Developer Toolkit Users Guide SOMobjects Developer Toolkit Programmers Reference Manual SOMobjects Developer Toolkit Collection Classes Reference Manual SOMobjects Developer Toolkit Emitter Framework Guide and Reference SOMobjects Developer Toolkit Installation/Configuration Guide ═══ 4. Base Operating System Services ═══ In general, base operating system APIs are specific to the local operating system and manage nondistributed resources such as processors, memory, and local devices. Base operating system APIs include functions such as memory management, event handling, and language services. DCE currently provides APIs for threads. These particular APIs provide some of the functions needed in a client/server environment. For more information on the base operating system APIs, see: Threads Internationalization ═══ 4.1. Threads ═══ Threads can be used to create efficient, fine-grained, concurrent programs. Each waiting event can be assigned to a thread that is blocked until the event occurs. In the meantime, other threads can use the processor cycles productively to perform useful work. The DCE Threads API provides the threads functionality needed in a DCE environment. For more information, see DCE Threads APIs ═══ 4.1.1. DCE Threads APIs ═══ This portable thread package runs in the user space and includes wrapper routines to translate calls to the operating system threads. Threads are an essential component of client-server applications and are used by other DCE components. The DCE thread APIs are based on the POSIX 1003.4a draft 4 (pthreads standard). The DCE threads also support multiprocessor environments using shared memory. DCE provides a semaphore service that helps threads synchronize their access to shared memory. The DCE Threads APIs are divided into the following functional groups: o General threads routines o Routines that implicitly perform threads initialization o Attributes object routines o Mutex routines o Condition variable routines o Thread-specific data routines o Cancellation routines o Priority and scheduling routines o Cleanup routines o Exceptions routine ═══ 4.1.1.1. General threads routines ═══ The following lists classify the Threads routines: pthread_create Creates a thread. pthread_delay_np Causes a thread to wait for a period of time. pthread_detach Makes a thread for deletion. pthread_equal Compares thread IDs. pthread_exit Terminates the calling thread. pthread_join Causes the calling thread to wait for the termination of a specified thread. pthread_once Calls an initialization routine to be executed only once. pthread_self Obtains the identifier of the current thread. pthread_yield Notifies the scheduler that the current thread will release its processor to other threads of the same or higher priority. ═══ 4.1.1.2. Routines that implicitly perform threads initialization ═══ pthread_attr_create Creates a mutual exclusion (mutex) attributes object. pthread_create Creates a thread. pthread cond_int Creates a condition variable. pthread_condattr_create Creates a condition variable attributes object. pthread_delay_np Causes a thread to wait for a period of time. pthread_getprio Obtains the scheduling priority attribute. pthread_getsched Obtains the scheduling policy attribute. pthread_keycreate Generates a unique thread-specific data key value. pthread_mutex_init Creates a mutex. pthread_mutexattr_create Creates a mutex attributes object. pthread_once Calls an initialization routine to be executed only once. pthread_self Obtains the identifier of the current thread. pthread_setasynccancel Enables or disables the current thread asynchronous canceling ability. pthread_setcancel Enables or disables the current thread general canceling ability. pthread_setprio Changes the scheduling policy attribute. pthread_testcancel Requests delivery of a pending cancel. ═══ 4.1.1.3. Attributes object routines ═══ pthread_attr_create Creates a thread attributes object. pthread_attr_delete Deletes a thread attributes object. pthread_attr_getinheritsched Obtains the inherit scheduling attribute. pthread_attr_getpio Obtains the scheduling priority attribute. pthread_attr_getsched Obtains the scheduling policy attribute. pthread_attr_getstacksize Obtains the stacksize attribute. pthread_attr_setinheritsched Changes the inherit scheduling attribute. pthread_attr_setprio Changes the scheduling priority attribute. pthread_attr_setsched Changes the scheduling policy attribute. pthread_attr_setstacksize Changes the stacksize attribute. pthread_condattr_create Creates a condition variable attributes object. pthread_condattr_delete Deletes a condition variable attributes object. pthread_mutexattr_create Creates a mutex attributes object. pthread_mutexattr_delete Deletes a mutex attributes object. pthread_mutexattr_getkind_np Obtains the mutex type attribute. pthread_mutexattr_setkind_np Changes the mutex type attribute. ═══ 4.1.1.4. Mutex routines ═══ pthread_lock_global_np Locks a global mutex. pthread_mutex_destroy Deletes a mutex. pthread_mutex_init Creates a mutex. pthread_mutex_lock Locks a mutex and waits if the mutex is already locked. pthread_mutex_trylock Locks a mutex and returns if the mutex is already locked. pthread_mutex_unlock Unlocks a mutex. pthread_unlock_global_np Unlocks a global mutex. ═══ 4.1.1.5. Condition variable routines ═══ pthread_cond_broadcast Wakes all threads waiting on a condition variable. pthread_cond_destroy Deletes a condition variable. pthread_cond_init Creates a condition variable. pthread_cond_signal Wakes one thread waiting on a condition variable. pthread_cond_timedwait Causes a thread to wait for a specified period of time for a condition variable to be signaled or broadcast. pthread_cond_wait Causes a thread to wait for a condition variable to be signaled or broadcast. pthread_get_expiration_np Obtains a value representing a desired expiration time. ═══ 4.1.1.6. Thread-specific data routines ═══ pthread_getspecific Obtains the thread-specific data associated with the specified key. pthread_keycreate Generates a unique thread-specific data key value. pthread_setspecific Sets the thread-specific data associated with the specified key. ═══ 4.1.1.7. Threads cancellation routines ═══ pthread_cancel Allows a thread to request termination. pthread_setasynccancel Sets the current thread's asynchronous canceling ability. pthread_setcancel Sets the current thread's general canceling ability. pthread_testcancel Requests delivery of a pending cancel. ═══ 4.1.1.8. Threads priority and scheduling routines ═══ pthread_getprio Obtains the current priority of a thread. pthread_getscheduler Obtains the current scheduling policy of a thread. pthread_setprio Changes the current priority of a thread. pthread_setscheduler Changes the current scheduling policy and priority of a thread. ═══ 4.1.1.9. Threads cleanup routines ═══ pthread_cleanup_pop Removes a cleanup handler from the stack. pthread_cleanup_push Establishes a cleanup handler. ═══ 4.1.1.10. Exceptions in DCE threads ═══ exceptions Describes exception handling in DCE threads. ═══ 4.2. Internationalization ═══ Internationalization of application programs consists of the ability to support features such as the characters of the native language (for instance, keyboards and presentation), as well as culture-specific information (for instance, time and date formats and collation/sorting), and user-visible text in the user's native language. For more information, see Internationalization (I18N) APIs. ═══ 4.2.1. Internationalization (I18N) APIs ═══ Specific APIs for I18N are listed according to the type of function, such as locale management and code set conversion. If the char data type is used, the multibyte APIs should be used. If locale information is needed, or if string handling includes insertion, deletion, truncation, or appending, the wchar_t APIs and data type should be used. Whenever wchar_t is used, it is necessary to convert from multibyte characters to wide characters using the Convert mb<->wc APIs. See the LAN Systems API Implementation Guidelines for further information. ┌───────────────┬───────────────┬───────────────┐ │Type of │Multibyte │wchar_t │ │function :C. │ │ │ │SBCS │ │ │ ├───────────────┼───────────────┼───────────────┤ │Locale │setlocale, nl_ │ │ │Management │langinfo, │ │ │ │localeconv │ │ ├───────────────┼───────────────┼───────────────┤ │Convert, mb< - │mbtowc, │wctomb, │ │>wc │mbstowcs │wcstombs │ ├───────────────┼───────────────┼───────────────┤ │Classification │ │iswalpha, isw* │ ├───────────────┼───────────────┼───────────────┤ │Case Mapping │ │towlower, │ │ │ │towupper │ ├───────────────┼───────────────┼───────────────┤ │Time/Monetary │strftime, │wcsftime │ │ │strptime, │ │ │ │strfmon │ │ ├───────────────┼───────────────┼───────────────┤ │String Copy │strcat, strcpy │wcscat, wcsncat│ │ │ │, wcscpy, │ │ │ │wcsncpy │ ├───────────────┼───────────────┼───────────────┤ │String Collate │strcoll, │wcscoll, │ │ │strxfrm │wcsxfrm │ ├───────────────┼───────────────┼───────────────┤ │String Length │strlen │wcslen │ ├───────────────┼───────────────┼───────────────┤ │String Search │ │wcschr, wcscspn│ │ │ │, wcspbrk, │ │ │ │wcsrchr, wcsspn│ │ │ │, wcstok │ ├───────────────┼───────────────┼───────────────┤ │IO Display │ │wcwidth, │ │Width │ │wcswidth │ ├───────────────┼───────────────┼───────────────┤ │IO Printf │printf, vprintf│printf, vprintf│ │ │, sprintf, │, sprintf, │ │ │vsprintf, │vsprintf, │ │ │fprintf, │fprintf, │ │ │vfprintf │vfprintf │ ├───────────────┼───────────────┼───────────────┤ │IO Scanf │scanf, sscanf, │scanf, sscanf, │ │ │fscanf │fscanf │ ├───────────────┼───────────────┼───────────────┤ │IO Character │ │fgetwc, fgetws,│ │ │ │fputwc, fputws │ ├───────────────┼───────────────┼───────────────┤ │Message │catopen, │ │ │ │catgets, │ │ │ │catclose │ │ ├───────────────┼───────────────┼───────────────┤ │Code Set │iconv_open, │ │ │Conversion │iconv, iconv_ │ │ │ │close │ │ └───────────────┴───────────────┴───────────────┘ ═══ 5. Distribution Services ═══ Distribution services assist in the communication between parts of distributed application and resource managers by providing common functions, such as: Directory Security Time Transaction ═══ 5.1. Directory ═══ The Directory service stores the names and attributes of all the resources in the network. Network resources may be logical devices such as queues or physical devices such as printers and servers. The Directory service provides a set of services and protocols accessed by way of a set of interfaces. For more information about directory-related APIs, see: o LAN Server Directory APIs o DCE Directory APIs o Future Directions for Directory ═══ 5.1.1. LAN Server Directory APIs ═══ LAN Server provides a directory at the domain level. This directory is stored at the domain controller and replicated to other servers in the domain to provide a single system image across all servers in the domain. LAN Server includes: o Aliases Aliases are persistent, shared resource definitions that provide location transparency and permanent storage of shared resource attributes. o Application definitions An application definition is a pointer to an executable file that resides on a server or on a client's local disk. The definition specifies attributes, such as resources to connect to when the application is started, parameters to pass to the application, and a working directory. These applications can be assigned to a user application selector so that they disply in a folder on the user's desktop when the user logs on. o Users, groups, and their attributes For more information on users and groups, refer to LAN Server Registry APIs. The following categories of LAN Server APIs are directory-related: o NetAlias o NetApp ═══ 5.1.1.1. NetAlias ═══ The functions in the Alias category examine or modify aliases. An alias is a nickname for a file, print, or serial device. An alias must be unique across the entire domain. An alias definition contains information to create a netname and initiate resource sharing. This information enables LAN Server to share the aliased resource automatically at server startup or at user request. The following APIs are in the Alias category: Net32AliasAdd Creates an alias definition. Net32AliasDel Deletes an alias definition. Net32AliasEnum Returns information about all aliases of a specified type. Net32AliasGetInfo Retrieves information about the specified alias. Net32AliasSetInfo Modifies information for an alias. ═══ 5.1.1.2. NetApp ═══ The functions of the Application category manage information about network applications. There are two types of data associated with applications: fixed data and list data. Fixed data includes the name of the application, the command line used to invoke the application, the application location (local or remote, alias or drive, and path), the name of a working directory (if any) associated with the application, and so on. List data consists of a set of zero or more structures that the application requires. For example, an application might require a resource containing certain data files. Redirections to these resources are made when the application is invoked. The redirections are deleted when the application stops. An application always has fixed data associated with it; it may or may not have list data associated with it. There are three application types: o Public DOS applications are available to users logged on to DOS LAN Requesters and to OS/2 LAN Requester users. o Public OS/2 applications are available only to users logged on at OS/2 LAN Requesters. o Private OS/2 applications are set up by individual users for their own use and are not available to other users. Program locations can be local or remote. If the location is local, the executable file used to start the application must be installed on each requester where it runs. If the location is remote, the application is stored on a server. The following APIs are part of the Application category: Net32AppAdd Adds an application definition. When a private application is added, the domain control database subdirectories must exist for the user. The Net32UserDCDBInit API initializes these subdirectories and files. Net32AppDel Deletes an application definition. Net32AppEnum Returns information about all applications of a specified type. If both public and private applications are to be enumerated, the return buffer contains public applications followed by private applications. Net32AppGetInfo Retrieves information about an application. Net32AppSetInfo Modifies information about an application. ═══ 5.1.2. DCE Directory APIs ═══ DCE provides international standards for naming interfaces and services. The X/Open Directory Service (XDS) interface provides interfaces for reading, adding, deleting, and modifying directory entries; attribute manipulation such as comparison and search; and enumeration of directory entries and its subordinates. The DCE Name Service Interface (NSI) and XDS interfaces are X/Open standards and part of X/Open's Distributed Computing Service profile. For more information on the NSI, refer to RPC Name Service Interface. The X/Open Object Management (XOM) API provides an interface to manage complex information objects. These information objects belong to classes and have attributes associated with them. There are two distinct kinds of classes and attributes: directory and object management (OM). The directory classes and attributes defined for the XDS API correspond to entries that make up the objects in the directory. These classes and attributes are defined in the X.500 directory standard and by additional CDS extensions created for DCE. Other APIs, such as the X.400 Application Interface, which is the application interface for the industry standard X.400 electronic mail service, define their own set of objects in terms of classes and attributes. OM classes and OM attributes are used to model the objects in the directory. The following categories of DCE APIs are directory-related: o XDS o XOM ═══ 5.1.2.1. XDS ═══ The XDS interface is available for use with the Cell Directory Service (CDS) and the X.500 directory service. DCE has multiple namespaces: o A global namespace (either X.500 or Domain Name System) to catalog cell names. o A cell namespace to contain server location information, profile information for the cell, and a list of hosts that make up that cell. o A security namespace to hold user, group, account, and policy information. o A file namespace to hold file data. The following APIs perform XDS functions: ds_abandon Abandons the result of a pending asynchronous operation. ds_add_entry Adds an entry to the directory information tree (DIT). ds_bind Opens a session with the Directory. ds_compare Compares a purported attribute value with the attribute value stored in the directory for a particular entry. ds_initialize Initializes the XDS interface. ds_list Lists the immediate subordinates of a particular directory entry. ds_modify_entry Performs an atomic modification on a directory entry. ds_modify_rdn Changes the relative distinguished name (RDN) of a leaf entry. ds_read Queries information on an entry by name. ds_remove_entry Removes an entry from the DIT. ds_search Finds entries of interest in a part of the DIT. ds_shutdown Shuts down the interface. ds_unbind Unbinds from a directory session. ds_version Negotiates features of the interface and service. Note: Some of these operations are not supported with the CDS. ═══ 5.1.2.2. XOM ═══ The XOM API provides a common information architecture so that the information objects defined for any API that conforms to this architectural model can be shared. Different application service interfaces can communicate using this common way of defining objects by means of workspaces. A workspace is a common work area where objects defined by a service can be accessed. The following APIs perform XOM functions: om_copy Creates a new private object that is an exact but independent copy of an existing private object. om_copy_value Places or replaces a string in one private object with a copy of a string in another private object. om_create Creates a new private object that is an instance of a particular class. om_delete Deletes a private or service-generated object. om_get Gets copies of attribute values from a private object. om_instance Tests an object class. om_put Puts attribute values into a private object. om_read Reads a segment of a string in a private object. om_remove Removes attribute values from a private object. om_write Writes a segment of a string into a private object. ═══ 5.1.3. Future Directions for Directory ═══ In LAN Server 4.0, alias definitions and application definitions are stored in the domain control database (DCDB). In future versions, this information is merged into the DCE cell directory service (CDS). Installation utilities automate this migration, and synchronization daemons build and maintain a replica of the DCDB information to preserve interoperability of downlevel clients and servers in the domain. The information in CDS can be manipulated using the DCE APIs (XDS and XOM), but LAN Server's NetAlias and NetApp APIs continue to be provided on LAN Server clients to allow existing applications that use these APIs to continue to work in this environment. For integrated clients, the LAN Server APIs are mapped directly onto CDS primitives. For basic clients and for legacy LAN Server clients, the APIs are directed to a domain controller, which maps them onto corresponding CDS APIs and sends them on to the CDS server. Hints: o The DCE Directory Service is a very versatile database which can be used to store and retrieve all kinds of data. The main use of a directory service for distributed applications is to provide a standard facility by which servers can advertise their location to clients. The NSI is tailored to this need and therefore simpler to use. The XDS interface is for developers who need access to the full functionality of DCE Directory Service as a generic directory service. o Many companies and standards organizations are converging on the X/Open XFN as a procedural interface to directory services and the OMG Naming Service interface as an Object Oriented interface. Both interfaces will be provided in future LAN Systems offerings, built as frameworks to allow developers to map the interfaces to existing directory stores including LAN Server 4.0 Aliases and Applications and DCE Cell Directory Service. Distributed SOM naming and directory services are integrated in this timeframe. ═══ 5.2. Security ═══ Security is concerned with identification and authentication of users, access control to resource, integrity of information, confidentiality of information, audit facilities, and management of security information. For more information on security-related APIs, see: o Authentication o Access Control o Registry o Auditing ═══ 5.2.1. Authentication ═══ Authentication provides a way for clients and servers to validate each other's identities. For more information about authentication APIs, see: o LAN Server Authentication APIs o DCE Authentication APIs o Network SignON Coordinator Authentication API o Future Directions for Authentication ═══ 5.2.1.1. LAN Server Authentication APIs ═══ User Profile Management (UPM) provides a set of user and group validation and management functions that help control access to information. User IDs and optional passwords are used to regulate data access. These IDs and passwords are assigned by a user with administrative authority. The following UPM APIs in the Authentication category: U32EULGN Logs a user onto the system. U32EULGF Logs a user off the system. U32ELOCL Invokes UPM to display a local logon window to allow users to enter their user IDs and passwords to perform a local logon to the system. U32ELOCU Invokes UPM to retrieve an ID of a user who has already logged on to the system as a local user. U32EUSRL Returns a list of logged-on user IDs. UPM APIs used in association with the following LAN Server API provide the authentication services needed in a LAN Server environment: Net32WkstaGetInfo Returns configuration information about a requester. For authentication, this API determines the identity of the user logged on to a requester. ═══ 5.2.1.2. DCE Authentication APIs ═══ The DCE Authentication APIs communicate with a security server to establish or change principal login context. A login context contains the information necessary for a principal to qualify for (although not necessarily be granted) access to network services. A login context normally includes the following information: o Identity context information concerning the principal. o The context state (that is, whether the authentication service has validated the context or not). o The source of authentication. (It may originate from the network authentication service, or locally, if the network service is unavailable.) The following Login APIs are in the Authentication category: sec_login_certify_identity Certifies the network authentication service. sec_login_export_context Creates an exportable login context. sec_login_free_net_info Frees storage allocated for principal network information. sec_login_get_current_context Returns a handle to the current login context. sec_login_get_expiration Returns the ticket-granting ticket lifetime for an authenticated identity. sec_login_get_groups Returns the group set from a login context. sec_login_get_pwent Returns a password-style entry for a login context. sec_login_import_context Imports a login context. sec_login_init_first Initializes the default context. sec_login_inquire_net_info Returns principal network information. sec_login_newgroups Changes the group list for a login context. sec_login_purge_context Destroys a login context and frees its storage. sec_login_refresh_identity Refreshes an authenticated identity for a login context sec_login_release_context Frees storage allocated for a login context. sec_login_set_context Creates network credentials for a login context. sec_login_setup_first Sets up the default network context. sec_login_setup_identity Sets up the user network identity. sec_login_valid_and_cert_ident Validates and certifies a login context. sec_login_valid_from_keytable Attempts to validate a login context using keys in the specified key table. sec_login_validate_first Validates the initial login context. sec_login_validate_identity Validates a login context's identity. ═══ 5.2.1.3. Network SignON Coordinator Authentication API ═══ The Network SignON Coordinator/2 is a productivity aid for DOS, Windows, and OS/2 end users whose environment requires multiple user signons to different access control functions. UPM, LAN Server, and Resource Access Control Facility (RACF) are examples of access control functions. Network SignON Coordinator/2 uses NSCRSIGN API, which performs sign-on, sign-off, and password change functions. ═══ 5.2.1.4. Future Directions for Authentication ═══ The LAN Systems programming environment will evolve over time to allow users to gain access to all resources on the system through a single logon, regardless of where the resources are stored in the system and which resource manager protects them. In the future, the base operating system will integrate its local logon with the DCE Authentication interfaces. In addition, the LAN Systems security architecture will provide a consistent network security context that correctly represents the identify of the user requesting resources on remote servers (secure association). The following secure association services will be provided: o authenticated RPC o secure conversations based on CPI-C o secure messages queues based on MQI Finally, the Generic Security Service Application Programming Interface (GSSAPI) included in OSF DCE 1.1 will allow application developers to build secure messages that can be sent across any communications medium to a GSSAPI-equipped communication partner. This interface is based on an emerging Internet standard. Hints: o The LAN Systems security architecture will provide several methods by which legacy DOS, Windows, and OS/2 applications can be integrated into the authentication architecture, such as: - Writing a script to allow the application client to receive its signon information from the Network Signon Coordinator - Modifying application client code to retrieve username and password information from the OS/2 security service - Rewriting the application communications code to use authenticated RPC, so that the application will accept DCE tickets. o The LAN Server Authentication APIs will be maintained for backward compatibility with existing LAN Server environments. ═══ 5.2.2. Access Control ═══ After clients are authenticated, server applications are responsible for verifying the operations clients are permitted to perform. Servers use access control lists (ACLs) to control user access. (ACLs are also referred to as access control profiles.) ACLs can be associated with any named computer resource. They contain the list of user and group names as well as the type of operations they can perform on each resource. Both DCE and LAN Server support authorization through ACLs. For more information on access control-related APIs, see: o LAN Server Access Control APIs o DCE Access Control APIs o Future Directions for Access Control ═══ 5.2.2.1. LAN Server Access Control APIs ═══ LAN Server Access Control APIs examine or modify user or group access permission records for server resources. For a user to access a shared resource, an ACL must be defined for that user. An ACL contains a set of permissions for each user or group. These permissions define how the user or group can access a shared resource. An ACL for a resource contains the following information: o The name of the resource o A list of users or groups, and their access permissions o An audit trail flag, which controls whether audit trail records are written for accesses to the resource. The following NetAccess APIs are in the Access Control category: Net32AccessAdd Defines a user name or group name ACL for a new resource. Net32AccessApply Replicates a previously-defined ACL for a directory and applies the profile to all subdirectories under that directory tree. This API also updates the ACLs for any files within the directory tree that have previous profiles, but it does not create a profile for files that do not already have one. Net32AccessCheck Verifies that a user has the proper access permission for a specified resource. Net32AccessDel Deletes all access permission lists for a specified shared resource. Net32AccessEnum Lists all ACLs. Net32AccessGetInfo Retrieves information about the ACL of a resource. Net32AccessGetUserPerms Supplies a specified user or group permission to a resource. The resource can be a file, directory, drive, or logical resource and can be specified remotely by a universal naming convention (UNC) path as well as by a server name. Net32AccessSetInfo Changes an ACL for a resource. ═══ 5.2.2.2. DCE Access Control APIs ═══ DCE Access Control APIs enable clients to browse or edit DCE ACLs and enable servers to perform DCE-conformant authorization checks at runtime. The following ACL and ID Map APIs are in the Access Control category: rdacl_get_access Reads a privilege attribute certificate. rdacl_get_manager_types Lists the types of ACLs protecting an object. rdacl_get_mgr_types_semantics Determines the types of ACLs protecting an object. rdacl_get_printstring Returns printable ACL strings. rdacl_get_referral Gets a referral to an ACL update site. rdacl_lookup Returns the ACL for an object. rdacl_replace Replaces an ACL. rdacl_test_access Tests access to an object. rdacl_test_access_on_behalf Tests access to an object on behalf of another process. sec_acl_bind Returns a handle for an object ACL. sec_acl_bind_to_addr Returns a handle to an object identified by its network address. sec_acl_calc_mask Returns the sec_acl_type_mask_obj entry for the specified ACL list. sec_acl_get_access Lists the permission set that the caller has for an object. sec_acl_get_error_info Returns error information from an ACL handle. sec_acl_get_manager_types Lists the manager types of the ACLs protecting an object. sec_acl_get_mgr_types_semantics Returns the types of ACLs and the POSIX semantics protecting an object. sec_acl_get_printstring Returns printable ACL strings. sec_acl_lookup Returns the ACL for an object. sec_acl_mgr_configure Configures an ACL manager. sec_acl_mgr_get_access Reads a privilege attribute certificate. sec_acl_mgr_get_manager_types Returns the types of ACLs that are protecting an object. sec_acl_mgr_get_printstring Returns printable ACL strings. sec_acl_mgr_is_authorized Compares a privilege attribute certificate with an ACL. sec_acl_mgr_lookup Finds an ACL using its key. sec_acl_mgr_replace Replaces an ACL. sec_acl_release Releases ACL storage. sec_acl_release_handle Removes an ACL handle. sec_acl_replace Replaces an ACL. sec_acl_test_access Tests access to an object. sec_acl_test_access_on_behalf Tests access to an object on behalf of another process. The ID Map API provides a simple interface to translate a fully-qualified name (that is, the global representation of a name) into its components and back again. This API consists of the following calls: sec_id_gen_group Generates a global name from cell and group UUIDs. sec_id_gen_name Generates a global name from cell and principal UUIDs. sec_id_parse_group Translates a global name into group and cell names and UUIDs. sec_id_parse_name Translates a global name into principal and cell names and UUIDs. ═══ 5.2.2.3. Future Directions for Access Control ═══ The LAN Systems programming environment will evolve over time to allow administration of access permission information for all resources, regardless of where the resources are stored in the system and which resource manager protects them. DCE-compliant ACL Managers will be the preferred method for resource managers to implement access control. In the future, a single, object-oriented programming interface will be provided for managing access control across multiple access control mechanisms. Hints: o Exporting the remote ACL editor API allows resource manager ACLs to be managed remotely by standard DCE utilities. o The LAN Server Access Control APIs will be maintained for backward compatability with existing LAN Server environments ═══ 5.2.3. Registry ═══ A registry stores security-related information, such as user account, group account, and password. For more information about registry-related APIs, see: o LAN Server Registry APIs o DCE Registry APIs o Future Directions for Registry ═══ 5.2.3.1. LAN Server Registry APIs ═══ In the LAN Server environment, the user accounts subsystem (UAS) stores the user account for each user or application that accesses resources in the system. The system uses this account to verify the user identity and to establish a context for that user. User account information includes attributes such as privilege level, account expiration date, list of authorized requesters, logon hours, password required, maximum storage allotment, and logon server. UAS information is replicated to all servers in a LAN Server domain, including single system images. The domain control database stores extended user information, such as logon assignments, application selectors, and logon profiles. The following NetLogon, NetUser and NetGroup APIs are in the Registry category: Net32LogonEnum Supplies information about logged-on users in a LAN Server domain. Net32UserAdd Establishes an account for a user in the UAS database and assigns a password and privilege level. Net32UserDCDBInit Initializes the domain control database for the specified user. Net32UserDel Removes an account from the UAS database, ending all access to the resources in the system. Deleting an account also deletes all references to that account in all resource permission access records and removes the account from groups in the system. Net32UserEnum Returns information about all accounts on a server. Net32UserGetAppSel Retrieves information about all specified types of applications contained in the user desktop application folders. Net32UserGetInfo Retrieves user attributes from the UAS, including privileges, home directory, and the status of an account. Net32UserGetLogonAsn Retrieves information about logon assignments for a user. Net32UserModalsGet Gets global policies for all users and groups in the UAS database. Net32UserModalsSet Sets global policies for all users and groups in the UAS database. Net32UserPasswordSet Changes the password for a user account. Net32UserSetApplSel Sets the list of applications contained in the specified user desktop application folders. Net32UserSetInfo Modifies a user account in the UAS database. Net32UserSetLogonAsn Sets logon assignments for a user. Net32UserValidate2 Validates a user with a password. This API verifies whether the user can log on based on logon restrictions defined for the account. Net32UserGetGroups Lists the names of all groups in the UAS database to which a specified user belongs. Net32UserSetGroups Sets the groups a user is a member of. A group is a set of users sharing common permissions in the UAS database. The Group APIs create or delete groups and review or adjust their membership. The following APIs are in the Group category: Net32GroupAdd Creates a new group account in the UAS database. Net32GroupAddUser Adds a user to a predefined group in the UAS database. Net32GroupDel Removes a group account from the UAS database. Net32GroupDelUser Removes a user from a specified group in the UAS database. Net32GroupEnum Lists all group accounts on the UAS database. Net32GroupGetInfo Retrieves group-related information Net32GroupGetUsers Returns a lists of members of a specified group in the UAS database. Net32GroupSetInfo Sets group-related information. Net32GroupSetUsers Sets information about users who belong to a specified group. ═══ 5.2.3.2. DCE Registry APIs ═══ The DCE Registry APIs enable a client to manage user and policy information in the DCE Registry service. The Registry and Key Management APIs are in the Registry category: sec_rgy_acct_add Adds an account for a login name. sec_rgy_acct_admin_replace Replaces administrative account data sec_rgy_acct_delete Deletes an account. sec_rgy_acct_get_projlist Returns the projects in an account project list. sec_rgy_acct_lookup Returns data for a specified account. sec_rgy_acct_passwd Changes the password for an account. sec_rgy_acct_rename Changes an account login name. sec_rgy_acct_replace_all Replaces all account data for an account. sec_rgy_acct_user_replace Replaces user account data. sec_rgy_auth_plcy_get_effective Returns the effective authentication policy for an account. sec_rgy_auth_plcy_get_info Returns the authentication policy for an account. sec_rgy_auth_plcy_set_info Sets the authentication policy for an account. sec_rgy_cell_bind Binds a registry in a cell. sec_rgy_cursor_reset Resets the registry database cursor. sec_rgy_login_get_effective Returns the effective login data for an account. sec_rgy_login_get_info Returns login information for an account. sec_rgy_pgo_add Adds a principal, group, or organization (PGO) item to the registry database. sec_rgy_pgo_add_member Adds a person to a group or organization. sec_rgy_pgo_delete Deletes a PGO item from the registry database. sec_rgy_pgo_delete_member Deletes a member of a group or organization. sec_rgy_pgo_get_by_id Returns the name and data for a PGO item identified by its UUID. sec_rgy_pgo_get_by_name Returns the data for a named PGO item. sec_rgy_pgo_get_by_unix_num Returns the name and data for a PGO item identified by its UNIX number. sec_rgy_pgo_get_members Returns the membership list for a group or organization. sec_rgy_pgo_get_next Returns the next PGO item in the registry database. sec_rgy_pgo_id_to_name Returns the name for a PGO item identified by its UUID. sec_rgy_pgo_id_to_unix_num Returns the UNIX number for a PGO item identified by its UUID. sec_rgy_pgo_is_member Checks group or organization membership. sec_rgy_pgo_name_to_id Returns the UUID for a named PGO item. sec_rgy_pgo_name_to_unix_num Returns the UNIX number for a PGO item identified by its name. sec_rgy_pgo_rename Changes the name of a PGO item in the registry database. sec_rgy_pgo_replace Replaces the data in an existing PGO item. sec_rgy_pgo_unix_num_to_id Returns the UUID for a PGO item identified by its UNIX number. sec_rgy_pgo_unix_num_to_name Returns the name for a PGO item identified by its UNIX number. sec_rgy_plcy_get_effective Returns the effective policy for an organization. sec_rgy_plcy_get_info Returns the policy for an organization. sec_rgy_plcy_set_info Sets the policy for an organization. sec_rgy_properties_get_info Returns registry properties. sec_rgy_properties_set_info Sets registry properties. sec_rgy_site_bind Binds to a registry site. sec_rgy_site_bind_query Binds to a registry query site. sec_rgy_site_bind_update Binds to a registry update site. sec_rgy_site_binding_get_info Returns information from the registry binding handle. sec_rgy_site_close Frees the binding handle for a registry server. sec_rgy_site_get Returns the string representation for a bound registry site. sec_rgy_site_is_readonly Checks whether a registry site is read only. sec_rgy_site_open Binds to a registry site. sec_rgy_site_open_query Binds a registry query site. sec_rgy_site_open_update Binds to a registry update site. sec_rgy_unix_getgrent Returns a UNIX-style group entry. sec_rgy_unix_getgrgid Returns a UNIX-style group entry for the account with the specified group ID. sec_rgy_unix_get_grnam Returns a UNIX-style group entry for the account with the specified group name. sec_rgy_unix_getpwent Returns a UNIX-style password entry. sec_rgy_unix_getpwnam Returns a UNIX-style password entry for the account with the specified name. sec_rgy_unix_getpwuid Returns a UNIX-style password entry for the account with the specified UUID. sec_rgy_wait_until_consistent Blocks updates while propagating prior updates to registry replicas. Every principal has an entry in the Registry database that specifies a secret key. In the case of an interactive principal (that is, a user), the secret key is derived from the principal password. In the same way users need to keep their passwords secure by memorizing them (rather than writing them down, for example), a noninteractive principal also needs to be able to store and retrieve its secret key in a secure manner. The Key Management API provides simple key management functions for noninteractive principals. The following routines make up the Key Management API: sec_key_mgmt_change_key Changes a principal key. sec_key_mgmt_delete_key Deletes a key from the local storage. sec_key_mgmt_delete_key_type Deletes a key version of a key type from the local key storage. sec_key_mgmt_free_key Frees the memory used by a key value. sec_key_mgmt_garbage_collect Deletes obsolete keys. sec_key_mgmt_gen_rand_key Generates a new random key of a specified key type. sec_key_mgmt_generate_key Generates a new random key. sec_key_mgmt_get_key Retrieves a key from local storage. sec_key_mgmt_get_next_key Retrieves successive keys from the local key storage. sec_key_mgmt_get_next_kvno Retrieves the next eligible key version number of a key. sec_key_mgmt_initialize_cursor Repositions the cursor in the local key store. sec_key_mgmt_manage_key Automatically changes a principal's key before it expires. sec_key_mgmt_release_cursor Releases the memory used by an initialized cursor value. sec_key_mgmt_set_key Inserts a key value into the local storage. ═══ 5.2.3.3. Future Directions for Registry ═══ In LAN Server 4.0, user definitions, groups, and policies are stored at the domain controller and replicated to backup and member servers. This system is referred to as the User Accounts Subsystem (UAS). In future versions, information stored in the UAS is merged into the DCE registry service. DCE acts as the master registry and this allows for a single user definition to be shared by all the subsystems that are integrated with DCE. It also brings the flexibility and scalability of the DCE user registry to LAN Server. In addition, a single, object-oriented programming interface for accessing and managing User Registry information across multiple user registries will be provided. Object Oriented Name Services (OONS) Framework or Extended Naming Context (ENC) interface will provide a single, consistent programming model for accessing information within one or more directory services without requiring the application to be aware of what underlying directory implementation actually satisfies a given request. The programming interface exported by the OONS framework is defined by the OMG Joint Object Services Submission Name Service Specification and the OMG Naming Extension Proposal. The LAN System programming environment will support this interface by insisting that LAN System cell users and policy be defined in an authoritative cell registry service, and that all other registries in the cell derive their information about such cell users and policies from that registry service. Hints: o Installation utilities will be provided with future versions of LAN Server to automate the migration from the UAS to the DCE registry service. API mapping is performed at the domain controller to translate UAS management and replications requests into operations on the DCE registry to preserve interoperability of downlevel LAN Server clients and servers in the domain. o The information in the DCE registry can be manipulated using the DCE APIs (sec_rgy_*), but LAN Server NetUser and NetGroup APIs will continue to be provided on LAN Server clients to provide a more LAN Server-centric interface to the registry information, and to allow existing applications that use these APIs to continue to work in this environment. For integrated clients, the LAN Server APIs are mapped directly onto sec_rgy APIs. For basic clients and for legacy LAN Server clients, the APIs are directed to a domain controller, which maps them onto corresponding sec_rgy APIs and sends them on to the DCE registry server. o To integrate other legacy application user registry into the DCE cell registry service, it is necessary to: - Accept registry information updates from the DCE registry service. Some user and group definition information in application registries will be common to the DCE registry service; this information can be extracted from the DCE registry using the sec_rgy interface provided today. Many legacy applications will have registry information that is not equivalent to any information in the standard DCE user or group definition records. This information will have to be stored in the DCE registry service as extended registry attributes associated with the appropriate GUI, and the legacy application's registry synchronization utility can manipulate this information through the extended registry attribute API provided with OSF DCE 1.1. - Provide a migration utility, based on the OSF-provided password_import utility, to move the contents of existing legacy application user and group names and existing DCE user and group names. - Optionally, plug in the LAN System registry framework by exporting a version of the OSF DCE 1.1 sec_rgy API. o The LAN Server Registry APIs will be maintained for backward compatability with existing LAN Server environments. ═══ 5.2.4. Auditing ═══ Auditing services enable the system to capture information about security-relevant events that occur in the system. For more information see: o LAN Server Auditing APIs o Future Directions ═══ 5.2.4.1. LAN Server Auditing APIs ═══ LAN Server provides an audit log file, which contains an audit trail of operations that occur on a server. This file stores information about how and when network resources are used as well as information about user IDs and their associated passwords. LAN Server can generate audit entries for the following types of events: o Change in server status o Beginning or end of a session o Password error o Start of a connection or a disconnection o Rejection of a connection request o Access made or rejection to a resource o Closing of a file, device, or pipe o Change of a service status code or text o Modification of an ACL or UAS database o Modification of the UAS database o Denial of a logon o Exceeding of an account limit The following APIs are part of the Auditing category: Net32AuditClear Clears the audit log file and optionally saves the contents to another file. Net32AuditRead Reads from the audit log on a server. Net32AuditWrite Writes an audit trail entry to the local audit log file. ═══ 5.2.4.2. Future Directions ═══ OSF DCE 1.1 includes Auditing APIs. These APIs will be the preferred interface for locally collecting and managing auditing information. Hint: o The LAN Server NetAudit APIs will be maintained for backward compatability with existing LAN Server environments. ═══ 5.3. Time Services ═══ A time service is a mechanism that allows clients and servers to synchronize their clocks. This time is coordinated with a universal time authority. For more information on time-related APIs, see: o LAN Server Time Service API o DCE Time Service APIs o Future Directions ═══ 5.3.1. LAN Server Time Service API ═══ The LAN Server Net32RemoteTOD API accesses the time-of-day information on a remote server. ═══ 5.3.2. DCE Time Service APIs ═══ DCE Time Service (DTS) APIs provide the time function needed in a DCE environment. These APIs provide a mechanism for synchronizing each computer in the network to a recognized time standard. These APIs manipulate timestamps and obtain universal time from public sources. DCE synchronizes time on its networks by maintaining agent-server and server-server relationships. Each DCE machine has a time clerk agent that asks time servers for the correct time and adjusts the local time accordingly. The agent can consult one or more time servers and calculate the probable correct time based on the responses it receives. The agent can upgrade the local time either gradually or abruptly. DCE requires at least three time servers, one or more of which must be connected to an external time provider. The time servers periodically query each another to synchronize their clocks. The external time provider can be a hardware device that receives time from a radio or a telephone source. DCE uses the Coordinated Universal Time (UTC) standard, which keeps track of time elapsed since the beginning of the Gregorian calendar. DTS provides the following functions: o Obtains timestamps that are based on UTC. o Translates between different timestamp formulas. o Performs calculations on timestamps. Applications can call the DTS routines from server or client systems and use the timestamps that DTS supplies to determine event sequencing, duration, and scheduling. The following terms are important for understanding DTS: Absolute time A point on a time scale. Absolute time measurements are derived from system clocks or external time-providers. Absolute timestamps refer to the UTC standard time and date and also include inaccuracy and other information. Relative time A discrete time interval that is often added to or subtracted from an absolute time. A time differential factor (TDF) associated with an absolute time is one example of a relative time. Coordinated Universal Time The international time standard that DTS uses. The zero hour of UTC is based on the zero hour (midnight) of Greenwich mean time (GMT). Time differential factor The difference between UTC and the time in a particular time zone. The user environment determines the time zone rule, but if the user environment does not specify a time zone rule, the system rule is used. The specifics of the user and system time zone rules are system-dependent. The APIs associated with the DCE time service are divided into the following functional groups: Time retrieval Retrieves the current (UTC-based) time from a DTS. Time conversion Converts binary timestamps expressed in the utc time structure to or from text strings or tm or timespec structure components. Time manipulation Manipulates the output of multiple UTC times and timestamps. Time comparison Compares two binary time values. Time calculation Calculates binary time values. Time zone information retrieval Obtains time zone information. ═══ 5.3.2.1. Time retrieval routines ═══ utc_gettime Returns the current system time and inaccuracy as a binary timestamp. utc_getusertime Returns the time and process-specific TDF, rather than the system-specific TDF. ═══ 5.3.2.2. Time conversion routines ═══ The following routines convert timestamps to tm structures: utc_anytime Converts a binary timestamp to a tm structure using the TDF information contained in the timestamp to determine the TDF returned with the tm structure. utc_gmtime Converts a binary timestamp to a tm structure that expresses GMT or the equivalent UTC. utc_localtime Converts a binary timestamp to a tm structure that expresses local time. utc_mkanytime Converts a tm structure and TDF (expressing time in an arbitrary time zone) to a binary timestamp. utc_mkgmtime Converts a tm structure that expresses GMT or UTC to a binary timestamp. utc_mklocaltime Converts a tm structure that expresses local time to a binary timestamp. utc_mkreltime Converts a tm structure that expresses relative time to a relative binary timestamp. utc_reltime Converts a relative binary timestamp to a tm structure. The following routines convert timestamps to timespec structures: utc_binreltime Converts a relative binary timestamp to two timespec structures that express relative time and inaccuracy. utc_bintime Converts a binary timestamp to a timespec structure. utc_mkbinreltime Converts a timespec structure expressing a relative time to a binary timestamp. utc_mkbintime Converts a timespec structure to a binary timestamp. The following routines convert timestamps to a text string: utc_ascanytime Converts a binary timestamp to a text string that represents an arbitrary time zone. utc_ascgmtime Converts a binary timestamp to a text string that expresses a GMT. utc_asclocaltime Converts a binary timestamp to a text string that represents a local time. utc_ascreltime Converts a binary timestamp to a test string that represents the relative time. utc_mkascreltime Converts a null-terminated character string that represents a relative timestamp to a binary timestamp. utc_mkasctime Converts a null-terminated character string that represents an absolute timestamp to a binary timestamp. ═══ 5.3.2.3. Time manipulation routines ═══ utc_boundtime Given two UTC times, one before and one after an event, returns a single UTC time whose inaccuracy includes the event. utc_pointtime Converts a binary timestamp to three binary timestamps that represent the earliest, most likely, and latest time. utc_spantime Given two (possibly unordered) binary timestamps, returns a single UTC time interval whose inaccuracy spans the two input binary timestamps. ═══ 5.3.2.4. Time comparison routines ═══ utc_cmpintervaltime Compares two binary timestamps or two relative binary timestamps. utc_cmpmidtime Compares two binary timestamps or two relative binary timestamps, ignoring inaccuracies. ═══ 5.3.2.5. Time calculation routines ═══ utc_abstime Compares the absolute value of a relative binary timestamp. utc_addtime Computes the sum of two binary timestamps. The timestamps can be two relative times or a relative time and an absolute time. utc_mulftime Multiplies a relative binary timestamp by a floating-point value. utc_multime Multiplies a relative binary timestamp by an integer factor. utc_subtime Compares the difference between two binary timestamps. The timestamps can be two relative times, two absolute times, or a relative time and an absolute time. ═══ 5.3.2.6. Time zone information retrieval routines ═══ utc_anyzone Gets the time zone label and offset from GMT, using the TDF contained in the input utc. utc_gmtzone Gets the time zone label for GMT. utc_localzone Gets the time zone label and offset, given utc. ═══ 5.3.3. Future Directions for Time ═══ DCE's utc_* time APIs offer a functionally richer alternative to the NetRemoteTOD API and this API set will be available on integrated and pure DCE clients and servers. Hint: o The LAN Server NetRemoteTOD API continues to be provided for retrieving the time of a LAN Server server for the sake of existing applications and to provide a common API across integrated and unintegrated clients. LAN Server clients will continue to export the API and LAN Server servers will accept the API. ═══ 5.4. Transactions ═══ Note to Rick Cohen Please ensure the appropriate review from NS. I have not updated this section from last time. I need details on future directions and probably some info on CICS. Under the control of a Transaction Processing (TP) Monitor, a transaction can be managed from its point of origin, typically on the client, across one or more servers, and then back to the originating client. When a transaction ends, all the parties involved are in agreement as to whether it succeeded or failed. The transaction becomes the contract that binds the client to one or more servers. Transaction APIs provide synchronization services so that multiple resource managers can act together to ensure that resources retain their integrity. The following groups of APIs are specific to transactions: o Encina Base APIs o Encina Server APIs o Encina General APIs o Encina Monitor APIs o Conversations o Record-Oriented File Services ═══ 5.4.1. Encina Base APIs ═══ The Encina Base feature of the AIX DCE Base Services/6000 supports the development of client/server transaction processing applications. Encina Base contains the following core APIs for defining transactional clients and servers: o Transactional C (Tran-C) o Transactional RPC (TRPC) o Transactional Protocol - Two Phase Commit ═══ 5.4.1.1. Transactional C (Tran-C) ═══ Transactional-C is the high-level API that simplifies transaction demarcation, concurrency control, and exception handling. Tran-C is made up of a set of macros and library routines for American National Standards Institute (ANSI)/Standard C. The following is a simple example of transaction definition: transaction { ... debit (salaryExpense, amount); credit (accountsPayable, amount); enterAuditData(employeeIdentifier, amount, date); ...} onCommit printf("Transaction succeeded."); onAbort printf("Transaction failed."); The bracketed statements of the transaction construct make up a single unit of distributed work. The onAbort clause simplifies the handling of exceptions in that any errors resulting in transaction abort are trapped within this branch. Under some circumstances, users may want to use the functions provided by TRAN, rather than using the equivalent higher-level functions Tran-C provides. ═══ 5.4.1.2. Transactional RPC (TRPC) ═══ The Transactional Remote Procedure Call (TRPC) module of the Encina Base service extends the DCE RPC with transaction semantics. Thus, remote computation initiated with a TRPC exhibits the properties of atomicity, consistency, isolation, and durability. If a standard RPC fails, the client generally cannot determine whether the message never arrived at the server, whether the server failed during the computation, or whether the return message was lost. This indeterminacy is unacceptable for transaction processing. When a transactional RPC fails, however, the encompassing transaction is aborted. When the semantics required for transaction processing are more restrictive, either a transaction is completed successfully by all participants, or an abort is issued, causing any local or remote modifications to be rolled back. To programmers, TRPC resembles the DCE RPC upon which it is based. The debit, credit, and enterAuditData calls of the preceding example are each intended to be TRPCs. Additionally, all of the DCE RPC features (the high-level API, name, and security service integration) are offered with TRPC as well. ═══ 5.4.1.3. Transactional Protocol - Two Phase Commit ═══ The Distributed Transaction Service (TRAN) module of the Encina Base service is the means by which a consensus is reached among transaction participants as to whether to commit or to abort a transaction. The actual standard for reaching this consensus is the two-phase, presume-abort commit protocol. Under this protocol, a transaction coordinator polls all participants. If each acknowledges that it is prepared to commit, the coordinator commits the pending transaction. If any participant does not wish to commit, the coordinator aborts the transaction. In either case, the coordinator informs all participants of the outcome. TRAN provides the logic for the two-phase commit protocol, but does not include a mechanism for communicating with other Transaction Services. Instead, it furnishes opaque transaction state information to the TRPC component for inclusion in transactional RPCs. The TRPC component then takes care of sending and receiving the messages required to execute the two-phase protocol. By separating communications and the transaction service, TRAN can be used with alternative communication facilities such as other RPCs or peer-to-peer implementations. A single instance of TRAN can support multiple communication mechanisms simultaneously, meaning that a transaction can send server requests in a number of different ways and yet still offer implicit two-phase commit over all participants. TRAN provides similar support for integrating multiple-recovery services, each of which provides the roll-forward and roll-back services for recoverable data. ═══ 5.4.2. Encina Server APIs ═══ The Encina Server provides for the management of recoverable data, which offers transactional integrity. The Encina Server comprises the following components: o Transactional Manager/XA (TM/XA) o Lock Service o Recovery Service o Volume Service o Log Service ═══ 5.4.2.1. Transactional Manager/XA (TM/XA) ═══ The TM/XA interface permits transactional access to XA-compliant databases (resource managers) to be accessed within Encina applications. Although client applications may use TM-XA, it must be used in conjunction with the Recovery service and the Log service. The XA interface is an X/Open standard for initiating and coordinating subordinate database transactions. ═══ 5.4.2.2. Lock Service ═══ The Lock service (LOCK) module of the Encina Server service provides a logical locking package to implement the serializability property of transactions. Acquired locks are transactional and by default are held until a transaction either committed or aborted. In addition to the standard shared (read) and exclusive (write) locks, the Lock Service supports hierarchical intention locks, whereby an entire file can be locked for either exclusive or shared access. For shared access, individual read and write locks are then granted for access to particular records. ═══ 5.4.2.3. Recovery Service ═══ The Recovery service (REC) module of the Encina Server service provides the undo and redo logic required to implement roll-back after an abort and roll-forward after a system failure. It also supports a recoverable memory abstraction that is realized by logging data updates. Before a transaction is committed, these log records are flushed to stable storage. By replaying this log, recoverable memory can be restored after system failure. Since the Recovery Service must support the Encina Structured File Server (SFS), it is essential that the Recovery service scale to represent very large address spaces of recoverable memory. ═══ 5.4.2.4. Volume Service ═══ The Volume service (VOL) module of the Encina Server service functions on top of the AIX Logical Volume Manager (LVM). The Volume service ensures that applications are more portable among versions of Encina on different platforms. To use the Recovery Service, the Volume service must be present, because REC calls the underlying VOL functions. ═══ 5.4.2.5. Log Service ═══ The Log service (LOG) module of the Encina Server service provides a write-ahead log for storing transaction outcomes and updates to recoverable data. Flexible archiving allows separate crash and media recovery logs to be produced from a single stream of log records. This service implements a common log, in that a single log may be shared among many participants for substantially better performance. An individual application, however, can view only its own log records. ═══ 5.4.3. Encina General APIs ═══ The following services are used throughout Encina but are not part of the Base or Service systems: o Trace o Administrative ═══ 5.4.3.1. Trace ═══ The Encina trace facility allows programmers to obtain various information about components and products. Components are modules such as TRAN, REC, and TRPC, whereas products are defined as lists of components. Products are full systems, such as the Encina Base and Encina Server, and SFS. Tracing can be turned on for a single component, an entire product, or any combination of components and products. The trace facility is a system observation tool that captures a sequential flow of time-stamped system events, providing a fine level of detail on system activity. Events are shown in time sequence and in the context of other events. It is a valuable tool for observing system and application execution. Where other tools provide high-level statistics, such as CPU utilization or I/O wait time, the trace facility is useful in expanding the information into detailed statistics. Encina uses AIX/6000 trace hook 0x294. ═══ 5.4.3.2. Administrative ═══ Encina servers rely heavily on DCE; consequently, DCE must be configured before Encina is. Encina is configured with the System Management Interface Tool (SMIT). SMIT uses interactive menus instead of command-line interfaces to guide administrators through configuration and other system management tasks. To begin basic Encina configuration with SMIT, enter the smit encina command at a command prompt. Each component of Encina may require configuration beyond the scope of basic configuration. This additional configuration can be accomplished through SMIT as well. For information about the administrative functions actually provided by the various modules of the Encina Server, refer to the Encina for AIX/6000 Base Reference or Encina for AIX/6000 Server Reference ═══ 5.4.4. Encina Monitor APIs ═══ The Encina Monitor extends the Encina Base and Server functions by offering a complete solution for open, distributed online transaction processing (OLTP). The features of the Encina Monitor can be separated into three areas of transaction processing application support: a development environment, an execution environment, and an administration environment. The Monitor libraries provide the following types of calls: Diagnostic facilities The diagnostic facilities of the Monitor allow application programs to report errors and other related information in a manner that is integrated with Monitor reporting mechanisms. The information is collected and then written to a file. Both clients and servers can use the diagnostic facilities. Environment retrieval The environment retrieval functions allow an application program to determine various characteristics of its execution environment. These functions primarily provide mechanisms for an application to construct an audit trail to ensure application integrity. Transaction control The transaction control functions provide a mechanism outside of Tran-C to initiate and control transactions. Transaction control only provides a subset of the features available to the Tran-C user; for instance, nested transactions are not supported. Transactional-C is the preferred mechanism for C programs to specify transactions. The transaction control functions allow transactional semantics to be bound to languages other than C. Server shared memory allocation and locking The server shared memory allocation and locking facility provides a mechanism for multiple application threads in an application server to share data and lock resources in a transactional manner. Some calls allocate shared memory areas, while others acquire and relinquish the right to read and write these areas. The shared memory functions primarily provide a performance boost in situations where transactional integrity is not necessary. The locking mechanism can be used without necessarily referencing shared memory. For instance, if an application server wishes to use a serially reusable device such as a tape drive or printer, concurrence can be controlled by locking a shared memory area that was never actually accessed. Timer Support Timer Support provides the ability to initiate an asynchronous local procedure call at a time designated by the calling program. Options provide the flexibility needed to satisfy various application needs. For more information on Encina Monitor APIs, see Messaging and Queuing. ═══ 5.4.4.1. Messaging and Queuing ═══ The IBM MQSeries Message Queue Interface (MQI) provides an interface for message-driven processing (such as asynchronous communications between programs). MQI also provides message forwarding between systems, message driven-processing through triggering facilities, and isolation from vendor queue service interfaces and data formats. Encina Recoverable Queuing Service (RQS) servers support transactional applications that must offload all or part of a task for later processing. The RQS enables data related to a task to be stored in queues and subsequently processed by client programs. This offloading may be desirable when use of a resource incurs an unacceptable time penalty during peak usage hours or when a resource is temporarily unavailable. The Encina RQS APIs are divided into the following categories: o Element type o Element o Locking o IDs o Queues o Queue set o Key o Cursor o RQS allocated memory o Batch o RQS server o RQS client Element type rqs_ElementTypeCreate Defines a new element type. rqs_ElementTypeDestroy Destroys an element type. rqs_ElementTypeRetrieve Retrieves an element type specification Element rqs_ElementDelete Deletes an identified element from its queue. rqs_ElementModify Modifies a specified value in an element. rqs_ElementRead Reads an identified element. Locking rqs_ElementDropLock Drops a lock held on the specified element. rqs_ElementListDropLocks Drops a lock held on each of the specified elements. ID rqs_ElementIdCmp Compares two element IDs. rqs_ElementIdToString Translates an element ID to a string. rqs_StringToElementId Translates a string into an element ID. Queue rqs_AcquireExclusiveAccess Obtains exclusive access to a queue. rqs_CallbackOnCumulativeWork Registers a callback dependent on the work accumulation for the queue. rqs_CallbackOnElementCount Registers a callback dependent on the number of elements in a queue. rqs_CallbackOnQueueSize Registers a callback dependent on the queue size in kilobytes. rqs_DeleteAllElements Removes all the elements from a queue. rqs_Dequeue Removes an element from a queue. rqs_EnableTransactionalAccess Enables full exclusive access for the current transaction. rqs_Enqueue Adds an element to a queue. rqs_QCreate Creates a new queue. rqs_QDestroy Destroys an existing queue. rqs_QStat Obtains information about a queue. rqs_ReleaseExclusiveAccess Releases exclusive access to a queue. rqs_Requeue Adds an orphaned element to a queue. rqs_RequeueAndModify Adds an orphaned element to a queue and modifies it. rqs_ResetStatisticsPeriod Resets the period of statistics collection for a queue. Queue Set rqs_InsertQueue Inserts a queue into a queue set. rqs_QSCreate Creates a new queue set. rqs_QSDequeue Removes an element from a queue set. rqs_QSDestroy Destroys an existing queue set. rqs_QSStat Obtains information about a queue set. rqs_RemovePriorities Removes specific priority classes from a queue set. rqs_RemoveQueue Removes a queue from a queue set. rqs_SetInfiniteServiceLevels Associates infinite service levels with all priority classes in a queue set. rqs_SetQueuePriority Associates a queue with a priority class with a queue set. rqs_SetServiceLevels Sets the service levels for priority classes in a queue set. Key rqs_RetrieveByKey Accesses elements by key value. rqs_RetrieveByKeys Accesses elements by intersecting multiple key retrievals. Cursor APIs rqs_CursorCopy Copies an existing cursor. rqs_CursorCreate Initializes a cursor for use on a queue. rqs_CursorDropLock Drops the last element lock held for cursor stability. rqs_CursorReadNext Reads an element and advances the cursor past it. rqs_CursorReadSequence Reads a specified number of elements and advances the cursor past them. rqs_CursorRelease Releases ownership of a cursor. rqs_CursorReset Resets a cursor to the beginning of its queue. RQS allocated memory rqs_Free Frees memory allocated by the RQS. Batch rqs_BatchElementDelete Appends an element-delete operation to a batch-call object. rqs_BatchElementModify Appends an element-modify operation to a batch-call object. rqs_BatchElementRead Appends an element-read operation to a batch-call object. rqs_BatchExecute Submits a batch-call object for execution. rqs_BatchFinalize Reclaims RQS internal structures associated with a batch-call object. rqs_BatchGetEntryInfo Describes the contents of a batch-call entry. rqs_BatchGetNumEntries Returns the number of entries in the batch-call object. rqs_BatchInitialize Initializes a batch-call object. rqs_BatchRequeue Appends a requeue operation to a batch-call object. rqs_BatchRequeueAndModify Appends a requeue-and-modify operation to a batch-call object. RQS server rqs_FreeServerHandle Closes a connection to an RQS server. rqs_GetServerHandle Obtains a binding handle to an RQS server. rqs_ServerStat Retrieves information about the status of an RQS server. rqs_SetCallbackRefreshPeriod Sets the client's maximum refresh period. rqs_SetCallbackRetentionPeriod Sets the server's retention period for callback registrations. rqs_SetClientTimeout Sets a client-specific period for a timeout class. rqs_SetServerTimeout Sets a server-wide default period for a timeout class. rqs_SetThreadTimeout Sets a timeout class's period for the next RPC in a thread. RQS client rqs_ClientInit Initializes an RQS client application. ═══ 5.4.5. Conversations ═══ The X/Open Common Programming Interface for Communications (CPI-C) provides an interface for applications to utilize peer programming. X/Open CPI-C was derived from the IBM System Application Architecture (SAA) CPI-C interface and modified to map to the OSI/TP, and therefore reflects OSI terminology and semantics. For more information on X/Open CPI-C, see X/Open Mainframe Data Access - CPI-C. Encina Peer-to-Peer Communications (PPC) Services extends the X/Open CPI-C interface by adding support for transaction processing with the support for the IBM SAA Common Programming Interface for Resource Recovery (CPI-RR). Encina PPC also offers the ability to operate between X/Open-based transaction processing systems and those systems that have System Network Architecture (SNA) LU-Type 6.2 SyncPoint Service support. ═══ 5.4.6. Record-Oriented File Services ═══ X/Open Indexed Sequential Access Method (ISAM) provides an interface for record-oriented operations. The interface provides operations that create and manipulate indexed data files. For more information on X/Open ISAM, refer to X/Open Data Management - Indexed Sequential Access Method (ISAM). The Encina Structured File Server (SFS) offers an X/Open-compliant ISAM interface called the Encina Transactional Indexed Sequential Access Method (T-ISAM). In addition to providing transactional data integrity for record-oriented operations, the Encina SFS also offers a virtual storage access method (VSAM)-style API with additional functionality for relative record operations. These capabilities also provide compatibility with the Informix C-ISAM interface. The Encina SFS provides the capability to use the SFS with Microfocus COBOL programs by supplying the Microfocus COBOL External File Handler (EXTFH) interface. ═══ 6. Communication Services ═══ Communication services provide mechanisms for parts of a distributed application or resource manager to talk to each other. For more information about communication services APIs, see: o Messaging and Queuing o Named Pipes o Event Notification o Remote Procedure Calls o Object Request Broker ═══ 6.1. Messaging and Queuing ═══ Messaging and queuing allows for general-purpose messages to be exchanged in a client-server system using message queues. Applications communicate over networks by placing and receiving messages in queues. Messaging and queuing allows clients and servers to communicate across a network without being linked by a private, dedicated, logical connection. For more information about messaging and queuing APIs, see: o LAN Server Mailslot APIs o Hints for Messaging and Queuing ═══ 6.1.1. LAN Server Mailslot APIs ═══ Data can be sent to either local or remote applications on a network through LAN Server mailslots. The Mailslot functions create and delete mailslots, retrieve information about either a mailslot or the message in it, and write messages to mailslots. Any application can write messages to any mailslot on any computer on the network by calling the Dos32WriteMailslot function. This function accepts mailslot names both in a local and remote format. Two classes of messages, first-class and second-class, can be sent to mailslots. First-class messages, limited to mailslots on local computers and remote servers, are guaranteed; the message is delivered or the sender is notified. Second-class messages are sent without any return code informing the sender of delivery. This simpler delivery system tends to make second-class messages faster than first-class messages. The following APIs are in the Messaging category: Dos32DeleteMailslot Deletes a mailslot. This API discards all read and unread messages. Dos32MailslotInfo Retrieves information about a specified mailslot. Dos32MakeMailslot Creates a mailslot and returns its handle. Dos32PeekMailslot Reads the next available message in a mailslot without removing it. Dos32ReadMailslot Reads and then discards the next available message of a mailslot. Dos32WriteMailslot Writes a message to a specified mailslot. ═══ 6.1.2. Hints for Messaging and Queuing ═══ Messaging and queuing allows applications to communicate with each other asynchronously through queue managers so that after the delivery is guaranteed, all the routing details are encapsulated inside queue managers and transparent to applications. The MQSeries family of products (IBM Messaging and Queuing Series), enable programs to talk to each other across a heterogeneous network using a simple and consistent API (MQI) that hides all the difficult work of communication. MQPUT, MQGET are the main functions that get and put messages in the queue. An application developer who develops a parallel distributed application should take advantage of the load balancing capabilities of messaging and queuing. For queue managers, IBM MQSeries provide generic message queue manager (MQM) functions: o Queue name-to-address resolution o Message routing o Message Channel Agent (MCA) o Administration o Sync point For more information on the IBM MQSeries of products, refer to the IBM An Introduction to Messaging and Queuing, GC33-0805. ═══ 6.2. Named Pipes ═══ A named pipe is a bidirectional IPC facility that allows two processes, either local or remote, to communicate with each other over a network. A process that creates a named pipe is known as a server process; a client process establishes a connection to a named pipe. An inbound or outbound named pipe (also known as anonymous pipes in some other multitasking operating systems) allows a process only to read or write by way of one handle. A full-duplex named pipe allows a process to read and write data by way of one handle. The following named pipes APIs are provided by the OS/2 base operating system and supported by LAN Server across the network: DosResetBuf Resets a specified buffer. DosCallNPipe Calls a named pipe. DosClose Closes a file or pipe. DosConnectNPipe Prepares a named pipe for a client process by placing the pipe into the listening state. DosDisConnectNPipe Acknowledges that a client process has closed a named pipe. DosDupHandle Copies a handle DosCreateNPipe Creates a named pipe. DosOpen Opens a file or pipe for reading or writing DosPeekNPipe Examines the data in a named pipe without removing the data. DosQueryFHState Determines whether a handle can be inherited and whether write-behind is allowed. DosQueryHType Returns the type of handle. DosQueryNPHState Returns the low-level parameters associated with a handle and the operating mode of the pipe. It also declares the instance count. DosQNPipeInfo Returns the size of buffers and the number of instances currently available. DosRead Reads from a file or pipe. DosReadAsync Reads from a file or pipe asynchronously. DosSetFHState Sets whether a handle of a named pipe can be inherited and whether write-behind is allowed. DosSetNPHState Sets low-level parameters associated with pipes such as reading and writing mode. DosSetNPipeSem Sets the association of a semaphore to a named pipe. DosWaitNPipe Waits for an instance of a named pipe to become available. DosWrite Writes to a file or pipe. DosWriteAsync Writes to a file or pipe asynchronously. ═══ 6.3. Event Notification ═══ The Event Notification APIs provide a system for notifying network server programs and applications of network events. See LAN Server Event Notification APIs for more information. ═══ 6.3.1. LAN Server Event Notification APIs ═══ An event is a particular instance of a process or state of hardware defined by an application or by the LAN Server software. LAN Server sends out an alert, in the form of a message or by the resetting of a semaphore, when certain events occur. The classes of events for the alerts include: o A print job was completed. o A user or application received a broadcast message. o An entry was added to an error log file. o A network event required administrative assistance. o A user accessed or used certain applications or resources. Other classes of alerts can be defined for network applications as needed. For example, if an application routinely writes large amounts of data to a disk drive, running the risk of filling the disk, an administrator might want the event of no free disk space to trigger an alert that notifies the application to pause or end the process that is slowing the system. The following NetAlert APIs are part of the Alert Notification category: Net32AlertRaise Notifies all clients registered as semaphores or mailslots in the alert table that a particular event has occurred. Net32Alert Start Registers a client to be notified of a particular type of network event. Net32AlertStop Removes a registered client from the alert table. ═══ 6.4. Remote Procedure Calls ═══ Remote procedure calls (RPCs) hide the intricacies of a network by using an ordinary procedure call mechanism. A client process calls a function on a remote server and waits until it receives the results. An RPC passes parameters in the same manner as ordinary procedures. For more information on RPC-related APIs, see: o LAN Server Remote Program Call API o DCE RPC APIs o Future Directions for SOM ═══ 6.4.1. LAN Server Remote Program Call API ═══ The LAN Server Net32RemoteExec API provides for remotely running a program on a remote server, redirecting standard input and output back to the client to allow user interaction. This API performs the same tasks as the DosExecPgm API, but on another network server. ═══ 6.4.2. DCE RPC APIs ═══ The DCE RPC Runtime facility manages both communications operations for RPC applications and operations that bind information. As part of server initialization, a server sets up its communications capabilities by a series of calls to the RPC Runtime facility. These runtime calls register the server RPC interfaces, tell the RPC Runtime facility what combination of communications protocols to use for the server, and register the endpoints of the server for each of its interfaces. After completing these and any other initialization tasks, the server tells the Runtime facility to begin listening for incoming calls. The Runtime facility also provides a variety of communications operations that allow servers to access and manipulate binding information. In addition, a set of communications operations enables applications to manipulate string representations of binding information (string bindings). The DCE RPC development environment includes: o UUID Generator o RPC Interface Definition Language o RPC Daemon o RPC Control Program o RPC Name Service Interface o Runtime Services ═══ 6.4.2.1. UUID Generator ═══ The DCE UUID generator is a utility that creates universal unique identifiers (UUIDs), hexadecimal numbers that contain information that make them unique from other UUIDs. This information includes a timestamp of the UUID creation time and an identifier of the host of origin. The following list shows RPC APIs that are associated with the DCE UUID generator. These routines are part of the DCE RPC Runtime facility, but are listed separately. uuid_compare Compares two UUIDs and determines their order. uuid_create Creates a new UUID. uuid_create_nil Creates a nil UUID. uuid_equal Determines whether two UUIDs are equal. uuid_from_string Converts a string UUID to its binary representation. uuid_hash Creates a hash value for a UUID. uuid_is_nil Determines if a UUID is nil. uuid_to_string Converts a UUID from a binary representation to a string representation ═══ 6.4.2.2. RPC Interface Definition Language ═══ Developing an RPC application involves writing and compiling an interface definition for a specific RPC interface that is written in the DCE interface definition language (IDL). The IDL is a high-level descriptive language whose syntax resembles that of ANSI C. DCE RPC interface definitions contain two basic components: an interface header and an interface body. The DCE IDL compiler processes RPC interface definitions written in DCE IDL and generates header files and stub object code. (The compiler can generate source code for the stubs written in ANSI C). The code generated from an RPC interface definition by the compiler includes client and server stubs that contain the RPC interface. The following routines perform stub memory management and stub support: rpc_sm_allocate Allocates memory within the RPC stub memory management scheme. rpc_sm_client_free Frees memory returned from a client stub. rpc_sm_destroy_client_context Reclaims the client memory resources for a context handle. rpc_sm_disable_allocate Releases resources and allocated memory in the stub memory management scheme. rpc_sm_enable_allocate Enables the allocation of memory by the rpc_sm_allocate routine when not in use. rpc_sm_free Frees memory allocated by the rpc_sm_ allocate routine. rpc_sm_get_thread_handle Gets a thread handle for the stub memory management environment. rpc_sm_set_client_alloc_free Sets the memory allocation and freeing mechanisms used by the client stubs. rpc_sm_set_thread_handle Sets a thread handle for the stub memory management environment. rpc_sm_swap_client_alloc_free Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client. rpc_ss_allocate Allocates memory within the RPC stub memory management scheme. rpc_ss_client_free Frees memory from a client stub. rpc_ss_destroy_client_context Reclaims the client memory resources for the context handle and sets the context handle to null. rpc_ss_disable_allocate Releases resources and allocated memory. rpc_ss_enable_allocate Enables the allocation of memory by the rpc_ss_allocate routine when not in manager code. rpc_ss_free Frees memory allocated by the rpc_ss_allocate routine. rpc_ss_get_thread_handle Gets a thread handle for either the manager code before it spawns additional threads, or for the client code when it becomes a server. rpc_ss_set_client_alloc_free Sets the memory allocation and freeing mechanism used by the client stubs, thereby overriding the default routines the client stub uses to manage memory for pointed-to nodes. rpc_ss_set_thread_handle Sets the thread handle for either a newly created spawned thread or for a server that was formerly a client and is ready to be a client again. rpc_ss_swap_client_alloc_free Exchanges the current memory allocation and freeing mechanism used by the client stubs with one supplied by the client. ═══ 6.4.2.3. RPC Daemon ═══ The RPC daemon is a server that provides the endpoint map service. An endpoint is the address of a specific instance of a server executing in a particular address space on a given system (a server instance). The endpoint map service maintains the local endpoint map for local RPC servers and looks up endpoints for RPC clients. Each endpoint can be used on a system by only one server at a time. ═══ 6.4.2.4. RPC Control Program ═══ The RPC control program is an interactive management utility for the administrators and users of RPC applications. The control program provides a means of managing namespace entries and endpoint mapping. Many operations of the RPC directory service interface are accessible using the control program. Individuals with the necessary permission can add entries to and remove them from a namespace, can add information to and remove it from these entries, and can retrieve information. Also, the control program enables displaying and deregistering endpoint map elements (or mappings) from the local endpoint map and any remote endpoint map. ═══ 6.4.2.5. RPC Name Service Interface ═══ The name service interface (NSI) routines perform on a namespace for RPC applications. The fundamental operations include the following: o Creating and deleting entries in namespaces. o Exporting. A server uses the NSI export operation to place binding information associated with its RPC interfaces and objects into the namespace used by the RPC application. o Importing. Clients can search for exported binding information associated with an interface and object using the NSI import operation or lookup operation. These two operations are collectively referred to as the NSI search operations. o De-exporting. The de-export operation enables a server to remove some or all of its binding information from a server entry. o Managing information in a namespace. Applications use the NSI interface to place information about server entries into a namespace and to query and manage that information. The following list shows RPC APIs that are associated with the name service interface. These routines are part of the DCE RPC runtime, but are listed separately. rpc_ns_binding_export Establishes a name service database entry with binding handles or object UUIDs for a server. rpc_ns_binding_import_begin Creates an import context for the interface and an object in the name service database. rpc_ns_binding_import_done Deletes the import context for searching the name service database. rpc_ns_binding_import_next Returns a binding handle of a compatible server from the name service database. rpc_ns_binding_inq_entry_name Returns the name of an entry in the name service database the server binding handle came from. rpc_ns_binding_lookup_begin Creates a lookup context for an interface and an object in the name service database. rpc_ns_binding_lookup_done Deletes the lookup context for searching the name service database. rpc_ns_binding_lookup_next Returns a list of binding handles of one or more compatible servers from the name service database. rpc_ns_binding_select Returns a binding handle from a list of compatible server binding handles. rpc_ns_binding_unexport Removes the binding handles for an interface or object UUIDs from an entry in the name service database. rpc_ns_entry_expand_name Expands the name of a name service database entry. rpc_ns_entry_object_inq_begin Creates an inquiry context for viewing the objects of an entry in the name service database. rpc_ns_entry_object_inq_done Deletes the inquiry context created by the rpc_ns_entry_object_inq_begin routine. rpc_ns_entry_object_inq_next Returns one object at a time from an entry in the name service database. rpc_ns_group_delete Deletes a group attribute. rpc_ns_group_mbr_add Adds an entry name to a group. If necessary, it creates the group entry. rpc_ns_group_mbr_inq_begin Creates an inquiry context for viewing group members. rpc_ns_group_mbr_inq_done Deletes the inquiry context for a group. rpc_ns_group_mbr_inq_next Returns one member name at a time from a group. rpc_ns_group_mbr_remove Removes a member from a group. rpc_ns_mgmt_binding_unexport Removes multiple binding handles or object UUIDs from an entry in the name service directory. rpc_ns_mgmt_entry_create Creates an entry in the name service database. rpc_ns_mgmt_entry_delete Deletes an entry from the name service database. rpc_ns_mgmt_entry_inq_if_ids Returns the list of interfaces exported to an entry in the name service database. rpc_ns_mgmt_handle_set_exp_age Sets a handle expiration age for local copies of name service data. rpc_ns_mgmt_inq_exp_age Returns the application global expiration age for local copies of name service data. rpc_ns_mgmt_set_exp_age Modifies the global expiration age for local copies of name service data. rpc_ns_profile_delete Deletes a profile attribute. rpc_ns_profile_elt_add Adds an element to a profile. If necessary, this routine creates the profile entry. rpc_ns_profile_elt_inq_begin Creates an inquiry context for viewing elements in a profile. rpc_ns_profile_elt_inq_done Deletes the inquiry context for a profile. rpc_ns_profile_elt_inq_next Returns one element at a time from a profile. rpc_ns_profile_elt_remove Removes an element from a profile. rpc_string_binding_compose Combines the components of a string binding into a string binding. rpc_string_binding_parse Returns the components of a string binding as separate strings. rpc_string_free Frees a character string allocated by the runtime facility. ═══ 6.4.2.6. Runtime Services ═══ Every RPC server or client must be linked with the RPC runtime facility that is part of the DCE runtime facility. The DCE RPC runtime facility manages communications for RPC applications. In addition, the DCE RPC runtime facility provides a library of routines to support RPC applications. An API enables server application code and client application code to call RPC routines to access runtime operations. The basic classes of runtime operations include the following: o Communications operations that establish communications links, transmit and receive remote procedure calls, and affect how data is transmitted. o Name service interface (NSI) operations that access namespace databases for RPC applications. o Endpoint operations that allow servers to add server addressing information to and remove it from the local endpoint map. o Authentication operations that affect the type of authentication, protection level, and type of authorization used for communications between a client and server. o Miscellaneous classes of operations, such as the UUID operations, with which applications manipulate UUIDs, and the management operations, which include a number of management operations such as stopping servers and diagnostics operations that assist error diagnosis. The following lists show which RPC APIs belong to the various classes of RPC runtime operations: ═══ 6.4.2.6.1. Communications operations ═══ rpc_network_inq_protseqs Returns all protocol sequences supported by the RPC runtime facility as well as the operating system client and server applications. rpc_network_is_protseq_valid Indicates whether the specified protocol sequence is supported by both the RPC runtime facility and the operating system. rpc_server_inq_bindings Returns binding handles for communication with a server. rpc_server_inq_if Returns the manager entry point vector registered for an interface. rpc_server_listen Tells the runtime to listen for RPCs. rpc_server_use_all_protseqs Tells the runtime to use all supported protocol sequences for receiving RPCs. rpc_server_use_all_protseqs_if Tells the runtime facility to use all the protocol sequences and endpoints specified in the interface specification for receiving RPCs. rpc_server_use_protseq Tells the runtime facility to use the specified protocol sequence for receiving RPCs. rpc_server_use_protseq_ep Tells the runtime facility to use the specified protocol sequence combined with the specified endpoint for receiving RPCs. rpc_server_use_protseq_if Tells the runtime facility to use the specified protocol sequence combined with the endpoints in the interface specification for receiving RPCs. ═══ 6.4.2.6.2. Endpoint operations ═══ rpc_ep_register Adds to or replaces server address information in the local endpoint map. rpc_ep_register_no_replace Adds to server address information in the local endpoint map. rpc_ep_resolve_binding Resolves a partially-bound server binding handle into a fully-bound server binding handle. rpc_ep_unregister Removes server address information from the local endpoint map. rpc_if_id_vector_free Frees a vector and the interface identifier structures it contains. rpc_if_inq_id Returns the interface identifier for an interface specification. rpc_mgmt_ep_elt_inq_begin Creates an inquiry context for viewing the elements in a local or remote endpoint map. rpc_mgmt_ep_elt_inq_done Deletes the inquiry context created by the rpc_mgmt_ep_elt_inq_begin routine. rpc_mgmt_ep_elt_inq_next Returns an element from a local or remote endpoint map. rpc_mgmt_ep_elt_unregister Removes server address information from a local or remote endpoint map. ═══ 6.4.2.6.3. Authentication operations ═══ rpc_binding_copy Returns a copy of a binding handle. rpc_binding_free Releases binding handle resources. rpc_binding_from_string_binding Returns a binding handle from a string representation of a binding handle. rpc_binding_inq_auth_client Returns authentication and authorization information from the client binding handle for an authenticated client. rpc_binding_inq_auth_info Returns authentication and authorization information from a server binding handle. rpc_binding_inq_object Returns the object UUID from a binding handle. rpc_binding_reset Resets a server binding handle so the host remains specified, but the server instance on that host is unspecified. rpc_binding_server_from_client Converts a client binding handle to a server binding handle. rpc_binding_set_auth_info Sets authentication and authorization information for a server binding handle. rpc_binding_set_object Sets the object UUID value into a server binding handle. rpc_binding_to_string_binding Returns a string representation of a binding handle. rpc_binding_vector_free Frees the memory used to store a vector and binding handles. rpc_server_register_auth_info Registers authentication information with the RPC runtime facility. rpc_server_register_if Registers an interface with the RPC runtime facility. rpc_server_unregister_if Removes an interface from the RPC runtime facility. ═══ 6.4.2.6.4. Miscellaneous operations ═══ rpc_mgmt_inq_com_timeout Returns the communication timeout value in a binding handle. rpc_mgmt_inq_dflt_protect_level Returns the default protection level for an authentication service. rpc_mgmt_inq_if_ids Returns a vector of interface identifiers of the interfaces a server offers. rpc_mgmt_inq_server_prince_name Returns a server principal name. rpc_mgmt_inq_stats Returns RPC runtime statistics. rpc_mgmt_is_server_listening Indicates whether a server is listening for RPCs. rpc_mgmt_set_authorization_fn Establishes an authorization function for processing remote calls to the server management routines. rpc_mgmt_set_cancel_timeout Sets a minimum time to wait before timing out after forwarding a cancel. rpc_mgmt_set_com_timeout Sets the communications timeout value in a binding handle. rpc_mgmt_set_server_stack_size Specifies the stack size for each server thread. rpc_mgmt_stats_vector_free Frees a statistics vector. rpc_mgmt_stop_server_listening Tells a server to stop listening for RPCs. rpc_object_inq_type Returns the type of an object. rpc_object_set_inq_fn Registers an object inquiry function. rpc_object_set_type Registers the type of an object with the RPC runtime. rpc_protseq_vector_free Frees the memory used by a vector and its protocol sequences. ═══ 6.5. Object Request Broker ═══ Note to Kim Update with specific classes. An object request broker (ORB) allows objects to communicate transparently with each other locally or across a network. o Distributed SOM o SOM-based Frameworks o Future Directions for SOM ═══ 6.5.1. Distributed System Object Model ═══ The system object model (SOM) handles the transparent distribution of objects. That is, application programs can access objects in other processes and across networks. SOM provides this transparent access to remote objects through its ORB. The location and implementation of the object are hidden from the client, and the client accesses the object as if it were local. The object management group (OMG) consortium defines an ORB as a mechanism that supports access to remote objects in a distributed environment. SOM complies with the OMG specification of common object request broker architecture (CORBA). The CORBA specification defines the components and interfaces that must be present in an ORB, including: o Interface definition language (IDL) for defining classes o C language usage bindings (procedure-call formats) for invoking methods on objects o Dynamic invocation interface and an interface repository, which support the construction of requests (method calls) at run time o ORB run-time programming interfaces. ═══ 6.5.2. SOM-based Frameworks ═══ To exploit this object-oriented paradigm in a more general way, frameworks are built to encapsulate the aspects of models and achieve the plug-in capability (replaceability) at the component level. Each component can be a single SOM object or more generally, an encapsulated set of SOM objects (including class objects) which: o Serves as a unit (object model) o Contains external interfaces, (dynamic model) o Contains internal interfaces, (functional model) In a framework, the single component itself can be distributed across the network and developers should ensure that the interfaces correctly encapsulate the component. Frameworks are usually packaged as sets of (dynamic or static) class libraries for particular capabilities, and application classes can be derived from them to acquire the behavior through (multiple) inheritance. The following SOM-based frameworks are available from IBM: o Distributed SOM (DSOM). DSOM allows application programs to access SOM objects across address spaces. This transparent access to remote objects is provided through its ORB; the location and implementation of the object are hidden from the client and the client accesses the object as though it were local. o Interface repository framework. The interface repository is a database that can hold all of the information contained in the IDL description of a class of objects. The interface repository framework consists of the 11 classes defined in the CORBA standard for accessing the interface repository. o Persistence framework. The persistence framework is a collection of SOM classes that provide methods for saving objects (either in a file or in a more specialized repository) and later restoring them. This means that the state of an object can be preserved beyond the termination of the process that creates it. o Replication framework. The replication framework is a collection of SOM classes that allows a replica (copy) of an object to exist in multiple address spaces while maintaining a single-copy image. Updates to any copy are propagated immediately to all other copies. This framework handles locking, synchronization, and update propagation, and guarantees mutual consistency among the replicas. o Emitter framework. The emitter framework is a collection of SOM classes that allows programmers to write their own emitters. Emitter is a general term used to describe a back-end output component of the SOM Compiler. Each emitter takes as input information about an interface and produces output organized in a different format. SOM provides a set of emitters that generate the binding for C and C++ language programming (header files and implementation templates). With SOM, IBM also provides a large group of classes and methods called the Collection Classes (sometimes called Foundation Classes). The purpose of the Collection Classes is to contain other objects. These classes can be used in client code "as is," or they can be used as the basis for deriving new classes. To exploit all of the benefits of the object management interfaces and services, application developers should choose programming tools that support SOM/DSOM. An example is VisualAge from IBM. IBM also provides the Direct to SOM compiler, which generates SOM-bindings from C++ language code, and SOM's Emitter framework, which can generate bindings from multiple languages. Also, the Microsoft-COM emitter for SOM is available allowing application developers building applications on SOM to achieve SOM-COM interoperability. ═══ 6.5.3. Future Directions for SOM ═══ SOM will evolve to address client/server scalability issues associated with naming, security, and interoperability for peer, workgroup, and enterprise environments: o Naming SOMobjects will provide an implementation of the OMG naming service based on DCE/CDS. This will give distributed SOM applications the ability to register objects that can be located by name and accessed from anywhere in the network. The benefits that CDS already offers can be exploited: a reliable, consistent, location-independent method for naming and accessing resources inside a cell. And if the CDS already contains objects such as RPC bindings to a server, those non-OO objects can still be accessed through the object-oriented services provided by SOMobjects. It is expected that the OMG naming services will be implemented on top of a number of directory services. At that point, multiple directories can be linked into a single name space. See Joint Object Services Submission; Naming Service Specification (Document 93.5.2), Object Management Group (OMG), Revised May 14, 1993, for more information on OMG Naming Services. This and other OMG documents can be obtained from OMG at: Object Management Group, Inc. Headquarters 492 Old Connecticutt Path Framingham, MA 01701 o Security DSOM will integrate the DCE Kerberos-based security services to support authenticated method-requests. The get_principal operation will reliably and securely identify who made the request. If the user could not be authenticated, the method request will not be passed to the object. Because DSOM will use the DCE registry, users have to be defined only once to the system. Users have to sign-on only once to use both RPC requests as well as DSOM requests. And because authentication is handled under the covers, applications do not have to be changed to run it securely. o Interoperability Version 2.0 of the SOMobjects product implements remote method calls using a native protocol, which includes simple data translation and object location services. The native protocol implementation is sufficient for the workgroup environments for which SOMobjects 2.0 was intended: small to medium size LANs of AIX, OS/2, and Windows systems. Future versions of DSOM will use DCE RPC to achieve a higher degree of scaleability and interoperability. In fact, IBM and a number of other companies (Hewlett-Packard, DEC, NEC, HyperDesk, and OSF) have proposed a standard protocol for interoperability among CORBA-compliant ORBs based on DCE RPC. See Joint Submission on Interoperability and Initialization (Document 94.3.5), Object Management Group (OMG), for more information on this proposal. Hint: It is important to understand that SOMobjects will not require DCE. All of the services previously described will also be available in a future version of SOMobjects without DCE. However, to enable an environment for scaleability and interoperability, DSOM will exploit the presence of DCE to achieve the desired quality of service. ═══ 7. Network Services ═══ Communications and networking are at the heart of the infrastructure for a distributed system. In today's world of heterogeneous, distributed computing, the higher level services and resource managers of the distributed system must support multiple operating system platforms and a variety of networking environments. At the same time, the higher level resource managers need program-to-program communication services that are suitable for their particular distribution model, but they cannot afford to be tied to specific networking protocols or data link protocols. This led to the structural separation of communication services and other transport users from network services. In 1992, IBM introduced the Networking Blueprint, its road map for networking in open, distributed systems, which focuses on the networking services, distributed services, and systems management portion of the Open Blueprint. The Networking Blueprint recognizes the need for structurally unifying network services by providing a common view of transport semantics, to make higher-level distributed systems services and application enabling services independent of the underlying transport network. This leads to the structure consisting of: o Common Transport Semantics o Transport Network Services o Telephony ═══ 7.1. Common Transport Semantics ═══ Transports provide reliable end-to-end communications across wide area networks (WANs) and local area networks (LANs) across various protocols, such as network basic input output system (NetBIOS), transmission control protocol/internet protocol (TCP/IP), and internet packet exchange/sequenced packet exchange (IPX/SPX). Common transport semantics support protocol-independent communication in the distributed network. For more information about common transport semantics, see: Socket API. ═══ 7.1.1. Socket API ═══ The socket API provides a standard interface to the transport and internetwork layer interfaces of Multi-Protocol Transport Services (MPTS). A socket is an endpoint for communication that can be named and addressed in a network. From an application program perspective, it is a resource allocated by the operating system. It is represented by an integer called a socket descriptor. Using the socket API model, applications can be written in a protocol-independent manner. By using the AF (address_family) option and by specifying a protocol-specific address, applications can choose a specific network protocol for communicating with remote transport applications. (Protocol-specific addresses are usually acquired from an application-level directory service such as DCE Cell Directory Service.) The remote transport application can be written to sockets, X/Open Transport Interface (XTI), or other transport protocol-specific APIs to communicate with NetBIOS. Sockets are supported on most operating system platforms: o Sockets (AF_OS2, AF_UNIX) for local domain is available on OS/2 and AIX. o Sockets (AF_INET) for TCP/IP is available for DOS, Windows (called Winsock), OS/2, and AIX. o Sockets (AF_NB) for NetBIOS is available on OS/2. o Sockets (AF_INET) over NetBIOS is available on OS/2. o Sockets (AF_INET) of SNA is available on OS/2, AIX, and MVS. The socket API supports four socket types: SOCK_STREAM Provides sequenced, two-way byte streams that are reliable and connection-oriented. They support a mechanism for out-of-band data. SOCK_STREAM is supported in the AF_OS2 (or AF_UNIX) and AF_INET domains. SOCK_SEQPACKET Provides sequenced, two-way byte records that are reliable and connection-oriented. SOCK_SEQPACKET is supported for protocols such as NetBIOS and AF_NETBIOS domains. When the NBPROTO protocol is specified, a socket application can be used to communicate with a remote application using the NetBIOS network control block (NCB) interface. SOCK_DGRAM Provides datagrams, which are connectionless messages of a fixed maximum length whose reliability is not guaranteed. Datagrams can be corrupted, received out of order, lost, or delivered multiple times. SOCK_DGRAM is supported in AF_OS2 (or AF_UNIX), AF_NETBIOS, and AF_INET domain. SOCK_RAW Provides the interface to internal protocols such as internet protocol (IP) and internet control message protocol (ICMP). SOCK_RAW is supported in the AF_INET domain. Stream, sequence packet, and datagram sockets interface to the transport layer protocols, and raw sockets interface to the TCP/IP network layer protocols. The following socket calls are protocol-independent: accept Accepts a connection request from a client on a server. bind Binds a unique local name to the socket. connect For stream or sequenced packet sockets, establishes a connection between two sockets. For datagram sockets, specifies the peer for a socket. getpeername Returns the name of the peer connected to a specified socket. getsockname Stores the current name for a socket into a structure. getsockopt Returns the values of socket options at various protocol levels. ioctl Controls operating characteristics. listen Completes the binding necessary for a stream socket. psock_errno Writes short error messages to the standard error display. readv Reads data on a socket and stores it in a set of buffers. This call applies only to connected sockets. recv Receives data on a socket and stores it in a buffer. This call applies only to connected sockets. recvfrom Receives data on any datagram socket and stores it in a buffer. recvmsg Receives messages on a socket and stores them in an array of message headers. select Monitors activity on a set of sockets to see whether any sockets are ready for reading or writing, or whether any exceptional conditions are pending. send Sends packets on a specified connected socket. sendmsg Sends messages on a specified socket passed in an array of message headers. sendto Sends packets on any datagram socket. setsockopt Sets options associated with a socket. This call can be called only for sockets in the AF_INET domain. shutdown Shuts down all or part of a duplex connection. sock_errno Returns the error code set by socket calls. sock_init Initializes the socket data structures. socket Creates an endpoint for communication and returns a socket descriptor representing the endpoint. soclose Closes the specified socket and frees the resources that were allocated to that socket. writev Writes data on a specified socket. ═══ 7.2. Transport Network Services ═══ The Open Blueprint supports a variety of network protocols for transporting information over both wide area and local area networks. These include: o Systems network architecture/advanced peer-to-peer networking (SNA/APPN) o Transmission control protocol/internet protocol (TCP/IP) o Open systems interconnection (OSI) o NetBIOS o Internet packet exchange (IPX) ═══ 7.2.1. NetBIOS API ═══ NetBIOS is a protocol for LAN-based program-to-program communications. It provides a naming service that allows a LAN adapter card to have multiple logical names. Through NetBIOS, applications can be written that exchange information between named entities on the network. The NetBIOS APIs are protocol-dependent; the socket APIs are protocol-independent. There are two types of NetBIOS APIs: o NetBIOS (NB30) o LAN Server NetBIOS Submit API ═══ 7.2.1.1. NetBIOS (NB30) ═══ NetBIOS (NB30) is available with MPTS, which is currently shipped with OS/2 DCE and LAN Server 4.0. NetBIOS provides a consistent API for applications to exchange information across a network so that applications themselves do not rely on a particular network and protocol. However, for NetBIOS actually to move the information through the network, it must use an underlying protocol, and applications wanting to communicate must use NetBIOS over an underlying protocol. For example, NetBIOS over TCP/IP uses TCP/IP as the transport mechanism. NetBIOS applications use names as the basis of addressing communication. An application registers the name by which it is known on the network, and NetBIOS maintains a table of names for all the applications on its host. A NetBIOS name can be unique, or it can be a group name. When an application registers a unique name, NetBIOS checks the network to verify that the name is not already in use; a group name can be used by several hosts simultaneously. For two applications to communicate, each must know the other's name. When an application knows the name of the application with which it wants to communicate, NetBIOS provides two basic types of data transfer: o Sessions o Datagrams A session is a reliable, full-duplex, guaranteed-delivery connection between two applications. If data is lost or corrupted, NetBIOS signals an error. Datagrams are a form of one-way communication that does not involve a connection. Datagrams can be lost or duplicated. With this type of data transfer, the receipt of the data is not guaranteed. Application programs communicate with NetBIOS using a control block called the network control block (NCB). The following parameters are included in the NCB: NCB_COMMAND Specifies the command to be performed by the adapter. NCB_RETCODE Indicates the completion status of the command. NCB_LSN Indicates the local session number. NCB_NUM Indicates a 1-byte number provided by the NetBIOS. NCB_BUFFER@ Contains the address of the buffer area as signed by the application program. NCB_LENGTH Indicates the length in bytes of the data buffer. NCB_CALLNAME Specifies the name of an adapter the application program wants to communicate with. NCB_NAME Specifies a node name on a network. NCB_RTO Specifies a timeout period for all receives associated with that session. NCB_STO Specifies a timeout period for all sends associated with that session. NCB_POST@ Indicates the presence of a post routine. NCB_DD_ID Indicates the identification number of the device driver. NCB_ADPRT_NUM Defines the adapter that is to be used. NCB_CMD_CMPL Indicates the completion status of the command. NCB_RESERVE A 14-byte reserved field that is used as a work area by NetBIOS applications. ═══ 7.2.1.2. LAN Server NetBIOS Submit API ═══ The NetBIOS functions may be needed when an application has already written directly to previous versions of a network interface. Application programmers should use mailslots and pipes, which are less dependent on the transport implementation, for network communications. The following NetBIOS Submit APIs are in the transport category: NetBios32Close Closes a handle to a network device driver. NetBios32Enum Returns information on all network device drivers installed on a computer. NetBios32GetInfo Returns information about a particular network device driver installed on a computer. NetBios32Open Opens a handle to a specified network device driver. NetBios32Submit Passes a NCB packet to a network device driver. ═══ 7.3. Telephony ═══ Note to Kim See if you can find into on CallPath Telephony is the use of systems for the transmission of voice or data communications between separate points. See LAN Distance API for more information about telephony-related APIs. ═══ 7.3.1. LAN Distance API ═══ The dial services interface (DSI) is an API that allows calls to be established across a network using the IBM LAN Distance program. An application using DSI can initiate, receive, and terminate connections between the LAN Distance Connection Server and LAN Distance Remote workstations. The connection can be over a switched line or leased line, using a synchronous, asynchronous, or integrated services digital network (ISDN) link. The remote workstations connected in this way communicate as though they were attached to the same LAN. DSI supports OS/2 32-bit and DOS Windows interfaces. Dial Services makes considerable use of the multitasking capabilities of IBM OS/2. When first started by an application, Dial Services allocates a work thread under the same process as the application. Dial Services receives subsequent requests on the thread of the application that issues the request and handed off to the work thread. The thread on which the request was made is then returned to the application, usually before the work associated with that request is complete. Changes in conditions caused by the DSI requests or events are generated on the work thread as they occur. When Dial Services is started, the application must specify an entry point in the application to be called by the work thread whenever an event occurs. These event calls run on the work thread and are serially submitted. The application event handler can be written assuming that one event is processed completely before the next event is received. Because events are processed on a separate thread that made the associated request, applications must treat events and requests as asynchronous. The DSI for DOS Windows is similar to DSI for OS/2, except that the event processor entry point is not 32-bit. Because of the architecture of DOS, an application using the DSI in DOS Windows can ensure that requests and events perform synchronously. Thus, an application designed for DOS may not work in OS/2. A design that handles events asynchronously as in the OS/2 environment should also work in DOS. The handling of multitasking differs, but the basic design is acceptable. Application writers should consider the features of the intended operating system carefully from the earliest stages of development. The following APIs are part of the DSI: DS_REQUEST_START_SERVICES Initiates the Dial Services Interface. DS_REQUEST_MAKE_CALL Makes a call to a remote computer. DS_REQUEST_HANGUP_CALL Completes a call either started by the DS_REQUEST_MAKE_CALL API or received on an autoanswer session. DS_REQUEST_START_AUTOANSWER Starts an autoanswer session. DS_REQUEST_STOP_AUTOANSWER Stops an autoanswer session. DS_START_QUERY Starts a query session. DS_STOP_QUERY Stops a query session. DS_DIAL_EVENT Enables an application to receive events pertaining to outstanding calls or autoanswer sessions as they occur. DS_QUERY_EVENT Enables an application to receive events pertaining to outstanding queries as they occur. ═══ 8. Application Enabling Services ═══ Application enabling services provide presentation services, application services, and data access services. For more information see: o Presentation Services o Application Services ═══ 8.1. Presentation Services ═══ Presentation services define the mechanism for interaction between applications and the user, using such graphical user interface elements as dialogs, icons, and menus. For more information see: o User Interface o Print/View ═══ 8.1.1. User Interface ═══ The graphical user interface (GUI) has become the focus for the presentation of information between the network and the user. The goal is to provide the information in a form that most closely matches objects that users deal with in the real world. This "look and feel" is accomplished by an object-oriented user interface in which the user manipulates objects with "point-and-click" and "drag-and-drop" actions. While today there are no common presentation services across desktop environments, IBM expects Taligent object frameworks to provide a rich set of presentation support controls (such as common desktop, window management, input event management, and multimedia) on all the major desktop platforms. For more information, see More about Objects. ═══ 8.1.2. Print/View ═══ Printing services enable users to print jobs and to manage print resources. A central goal for printing is to provide users with a single system image of the printing environment. This means that applications are written to APIs that hide the complexity of the printing environment. The result is a single system image that hides the following: o The physical location of the print objects accessed through the print APIs. o The specific print service providers that are processing the APIs and implementing the print objects. o The protocols used by a service provider to communicate print requests to and receive status from print services in response to the APIs. Today, the print APIs and the corresponding print objects supported by those APIs are based on the print service providers for the operating systems an application runs on. Print objects typically supported include job, queue, and printer, where: o A job is a printable entity with options, such as number of copies and print quality. o A queue is a repository for jobs that are scheduled for one or more printers supported by the queue. o A printer is a physical device a job is printed on. On OS/2, the single-system image is provided by the procedural print framework. This framework enables applications written to the APIs for OS/2 Presentation Manager (PM), OS/2 (non-PM), DOS, and Windows to transparently print on locally or remotely attached printers. Furthermore, applications can manage print objects through APIs, regardless of the physical location of these print objects. This single-system image is accomplished through print service providers, such as the local OS/2 print service and the remote print services of OS/2 LAN Server and Novell NetWare, that are installed below the procedural print framework and, as a result, map the APIs supported by the framework to the specific operations and protocols supported by the respective print services. On AIX/6000, the single-system image is provided by the AIX/6000 print subsystem. Print queues can be assigned to locally attached or remotely attached printers and accessed transparently by applications through the command line interfaces (CLIs) supported by AIX/6000. Because these CLIs serve as the programming interfaces for printing in AIX/6000, these CLIs are listed in the inventory of print APIs. AIX/6000 supports CLIs from the Berkeley Software Distribution (BSD) and ATT UNIX systems to enable users and applications to continue to use those commands. These commands are so noted in the inventory. However, AIX/6000 supports more printing function than either the BSD and ATT UNIX system. Therefore, the AIX/6000 CLIs should be used in order to fully utilize the printing capabilities of AIX/6000. For more information about print APIs, see: o Job Submission o Print Object Management o Future Directions for Print ═══ 8.1.2.1. Job Submission ═══ An application submits a print job to a queue. The job consists of print service options, job properties, and data that is printable (for example, PostScript) by the target printer. The data can be printed on the target printer supported by the queue or the data can be translated by the print service that processes the data on behalf of the target printer. OS/2 (non-PM) applications use the following APIs to submit print jobs: SplEnumQueue Returns a list of queues. SplQmAbort Stops the generation of a spool file. SplQmAbortDoc Aborts a print job. SplQmClose Closes a spool file for a print job. SplQmEndDoc Ends a print job. SplQmOpen Opens a spool file for generating a print job. SplQmStartDoc Starts a print job. SplQmWrite Writes data to a spool file for a job. SplQueryQueue Retrieves the job properties of a queue. OS/2 PM applications use the following APIs to submit print jobs: DevCloseDC Closes a device context for a print job. DevEscape DEVESC_ABORTDOC Aborts a print job. DevEscape DEVESC_ENDDOC Ends a print job. DevEscape DEVESC_NEWFRAME Starts a new page in a print job. DevEscape DEVESC_STARTDOC Starts a print job. DevOpenDC Opens a device context for a print job. DevPostDeviceModes Displays the job properties of a queue so the user can view or change these properties for a print job. The user's choices are returned to the application. Gpi* Draws the desired output. SplEnumQueue Returns a list of queues. SplQueryQueue Retrieves the job properties of a queue. AIX/6000 applications use the following CLIs to submit print jobs: enq Submits a print job. lpr Submits a print job (BSD UNIX). lp Submits a print job (ATT UNIX). lsallq Returns a list of queues. qprt Submits a print job. ═══ 8.1.2.2. Print Object Management ═══ An application enables a user or administrator to create, delete, modify, list, and control print objects. Most applications do not need to manage print objects. OS/2 PM and non-PM applications use the following APIs to manage print objects: SplControlDevice Cancels, holds, releases, or restarts a device. SplCopyJob Copies a job in a queue. SplCreateDevice Creates a device. SplCreateQueue Creates a queue. SplDeleteDevice Deletes a device. SplDeleteJob Deletes a job from a queue. SplDeleteQueue Deletes a queue. SplEnumDevice Lists devices on the local workstation or on a remote server. SplEnumDriver Lists printer drivers on the local workstation or on a remote server. SplEnumJob Lists jobs in a queue. SplEnumPort Lists ports (for example, LPT1) on the local workstation or on a remote server. SplEnumQueue Lists queues on the local workstation or on a remote server. SplEnumQueueProcessor Lists queue processors on the local workstation or on a remote server. SplHoldJob Holds a job in a queue. SplHoldQueue Holds a queue. SplPurgeQueue Deletes all jobs in a queue. SplQueryDevice Retrieves information about a device. SplQueryJob Retrieves information about a job. SplQueryQueue Retrieves information about a queue. SplReleaseJob Releases a held job. SplReleaseQueue Releases a held queue. SplSetDevice Modifies the configuration of a device. SplSetJob Modifies the settings for a job. SplSetQueue Modifies the configuration of a queue. AIX/6000 applications use the following CLIs to manage print objects: cancel Deletes a job from a queue (ATT UNIX). chque Modifies the name and attributes of a queue. chquedev Modifies the name and attributes of a queue device. chvirprt Modifies the attributes of a virtual printer. disable Disables a print queue (ATT UNIX). enable Enables a print queue (ATT UNIX). enq Manages print server functions. lpq Retrieves information about a job (BSD UNIX). lprm Deletes a job from a queue (BSD UNIX). lpstat Retrieves information about a queue (ATT UNIX). lsallq Lists all queues. lsallqdev Lists devices on a queue. lsattr Lists attributes of a device. lsque Lists attributes of a queue. lsquedev List devices and device information for a queue. lsvirprt Lists attributes of a virtual printer. mkque Creates a queue. mkquedev Creates a device. mkvirprt Creates a virtual printer. qadm Specifies printers or queuing systems to be brought down or up. qcan Deletes a job from a queue. qchk Retrieves information about a job. qpri Sets and modifies the priority for a job. rmque Deletes a queue. rmquedev Deletes a device. rmvirprt Deletes a virtual printer. splp Lists or modifies printer driver settings. DOS applications use the following APIs to manage print objects: DosPrintDestAdd Creates a device. DosPrintDestControl Cancels, holds, releases, or restarts a device. DosPrintDestDel Deletes a device. DosPrintDestEnum Lists devices on the local workstation or on a remote server. DosPrintDestGetInfo Retrieves information about a device. DosPrintDestSetInfo Modifies the configuration of a device. DosPrintDriverEnum Lists printer drivers on the local workstation or on a remote server. DosPrintJobContinue Releases a held job. DosPrintJobDel Deletes a job from a queue. DosPrintJobEnum Lists jobs in a queue. DosPrintJobGetInfo Retrieves information about a job. DosPrintJobPause Holds a job in a queue. DosPrintJobSetInfo Modifies the settings for a job. DosPrintPortEnum Lists ports on the local workstation or on a remote server. DosPrintQAdd Creates a queue. DosPrintQContinue Releases a held queue. DosPrintQDel Deletes a queue. DosPrintQEnum Lists queues on the local workstation or on a remote server. DosPrintQGetInfo Retrieves information about a queue. DosPrintQPause Holds a queue. DosPrintQProcessorEnum Lists queue processors on the local workstation or a remote server. DosPrintQPurge Deletes all jobs in a queue. DosPrintQSetInfo Modifies the configuration of a queue. ═══ 8.1.2.3. Future Directions for Print ═══ The IBM distributed print management framework (DPMF), based on Palladium Version 2, will support distributed printing and print systems management across a multi-vendor environment by supporting emerging open systems standards such as the ISO document printing application (DPA) 10175, IEEE POSIX 1387.4 and the X/Open print interoperability standard. DPMF will also support a selected set of programming interfaces that are available today in OS/2 and AIX. This will enable applications written to those interfaces to transparently access printers and manage print resources supported by DPMF. In short, DPMF will be a print service provider on OS/2 and AIX. In addition, application developers who write to the object-oriented print APIs supported by the Taligent application environment (TalAE) will print on printers supported by the print service providers in OS/2 and AIX, because the TalAE uses the print APIs of OS/2 and AIX for printing. The TalAE APIs will be defined using IBM SOM. In the future, the print APIs and the corresponding print objects supported by the APIs will be standardized across OS/2 and AIX to enable true application portability across a multi-system environment. Application developers will be able to use a single set of object-oriented APIs for end-user and systems management functionality, regardless of the physical location of the printer and print resources being used and managed. These APIs will be defined using IBM SOM and will work in the Taligent environment. Applications written to the printing APIs in the TalAE will continue to run. Hints: To preserve customers' current investments in software applications, a specified set of legacy programming interfaces will be supported on each operating system. o The following sets of APIs in OS/2 will be supported on future releases of OS/2 systems to enable applications written to these APIs today to run in the future: Dev* OS/2 PM applications SplQm* OS/2 applications Spl* OS/2 and PM applications Dos* DOS and Windows applications o The DosPrint* APIs will not be supported in future versions of OS/2. Application developers should use the equivalent 32-bit Spl APIs to deliver applications that are portable across OS/2 on Intel. o The following sets of CLIs in AIX will be supported on future releases of AIX systems to enable applications written to these CLIs today to run in the future: lp BSD UNIX applications lpr ATUNIX applications qprt and related AIX CLIs AIX applications enq AIX applications ═══ 8.2. Application Services ═══ Application services are common functions, such as mail, which are available for use by all applications. ═══ 8.3. Mail ═══ Mail is an electronic mechanism for users to exchange a wide variety of forms such as text, rich text, graphics images, and video. Mail can be modeled as User Agents(clients) which interact with Message Transfer Agents(servers). User Agents (UAs) provide user and application access to the mail system in the form of send, compose, and reply functions. In addition several industry wide programatic APIs have emerged, see (Mail APIS). Message Transfer Agents receive mail requests from User agents, and typically are responsible for "executing" the appropriate tranformation, routing, and message store functions. These Message Transfer agents typically interoperate with a variety of "backbone" protocols such as X.400, SMTP, and SNADS. There are many other aspects to this model as well; typically a mail system has enterprise address books which support multiple "mail types" as well as synchronization with other mail system address books. Additonally, the message transfer agents also sup port or have support for gateways to other mail systems which are not supported natively. Also, the user agents, are required to support a disconnected mode of operation; which allow a user's folders and in-baskets to be stored on a disconnected client, allow a disconnected user to operate on mail as if connected, and then perform a connect and resynchronization function with the message transfer agent (server). Mail Versus Messaging Mail is distinguised from Messaging, such as MQSERIES, by the fact that mail is "non-real time", store and forward delivery, whereas messaging provides assured, queued once only delivery as well as the capability to support transaction type processing. Many companys today, when referring to their emerging enterprise messaging servers, are really referring to mail servers described above. Shared File Versus Client-Server Mail Many of the original LAN based E-MAIL systems, consisted of only user agents. Mail forwarding was really only the clients "pushing" the messages into passive shared files (called "postoffices"). These systems work fine for relatively small numbers of LAN based users, but attempts to scale these systems to enterprise level have been unsuccessful; as a result much of the industry had announced intent to provide enterprise mail products using the user agent (client) to message transfer agent(server) model described above. For more information on mail-related APIs, see: o LAN Server NetMessage API o Mail APIs o Future Directions for Mail and Messaging ═══ 8.3.1. LAN Server NetMessage API ═══ The LAN Server NetMessage API provides simple messaging services that allow users to send, log, and forward messages. A message is any file or buffer of data sent to a messaging name on the network. A message name is either a user or an application. To receive a message, a user or application must register a messaging name in the message name table. A message name table contains a list of registered messaging names permitted to receive messages and a list of users and applications to which a message can be forwarded. The following APIs are in the Message category: Net32MessageBufferSend Sends a buffer of information to a registered messaging name. Net32MessageFileSend Sends a file to a registered messaging name. Net32MessageLogFileGet Retrieves the name of the message log file as well as the current logging status. Net32MessageLogFileSet Specifies the file where messages are to be logged on a particular server. This API also enables or disables the logging process. Net32MessageNameAdd Registers a name in a message name table. Net32MessageNameDel Deletes names from a message name table. Net32MessageNameEnum Lists all the name entries stored in a message name table. Net32MessageNameFwd Modifies the message name table to forward messages to another messaging name. Net32MessageNameGetInfo Retrieves information about a specified user listed in the message name table. Net32MessageNameUnFwd Cancels message forwarding. ═══ 8.3.2. Mail APIs ═══ Several Open Interface Mail APIs have emerged in the industry for providing programatic access to mail functions directly to applications. Several companys, including IBM, were members of the Vendor Independent Messaging Consortium, and produced the VIM 1.0 specification. VIM is intended to be a multiplatform standard that can be implemented by a variety of products running in different environments. Microsoft produced the MAPI messaging interface for Windows environments. As a result, and in order to ac hieve an industry goal of one set of mail API specifications, the VIM consortia, along with others, worked within the context of the X/OPEN API Association to produce the Common Messaging Calls Version 1.0 specification. This CMC specification is a basic set of messaging API functions, providing a subset of both the VIM and MAPI specifications. Currently XAPIA is working on a "richer" version of CMC, CMC 2.0. This specification is expected to be out of XAPIA in the first half of 1995. As this specification gains ISV acceptance, the need for continued support for multiple APIs should diminish. ═══ 8.3.3. Future Directions for Mail and Messaging ═══ At the November 1994 COMDEX, IBM announced its IBM Workgoup Mail-Messaging strategy. A brief summary of this strategy is listed here: 1. Provide an Open customizable framework for a comprehensive messaging solution that allows for a mix and match of messaging components from IBM and other vendors. 2. Provide a fully scaleable, client server(see above), information structure that encompasses messaging and extends to other vital areas of information management. 3. Provide a messaging transport layer that transcends the differences between transport protocols such as X.400, SMTP/MIME, SNADS, and others. 4. Integrate this solution with ISV and IBM workgroup applications via industry standard APIs/SPIs such as VIM, MAPI and CMC. 5. Provide and easy path for both coexistence and/or migration from other E-mail systems. 6. Deliver this solution across multiple hardware and software platforms. Hint A version of the mail component of IBM Workgroup, (UltiMail Lite), recently shipped as a part of the Bonus Pak of OS/2 Warp. ═══ 9. System Management Services ═══ In the distributed environment, the need for system management has become a high customer priority. Customer requirements include the ability to manage both local and remote systems using basic system administration skills. System management requirements are defined for applications so that, when the applications are shipped, a common set of management functions and applications allows customers to manage their systems. For more information on system management APIs, see: o Installation and Distribution o Configuration o Network Operating System Management o Reliability/Availability/Serviceability o Licensing ═══ 9.1. Installation and Distribution ═══ Installation makes an application executable on the workstation. Feature selection can determine what code is actually installed on the workstation. Distribution enables management of code servers, code packages, customer workstations, and groups of workstations. For more information, on installation and distribution APIs, see : o CID o Hints for Installation and Distribution ═══ 9.1.1. CID ═══ The Configuration, Installation, and Distribution (CID) utility, a product for OS/2, DOS, and Windows, helps to consolidate the resources needed for workstation administration and to eliminate the need for installation expertise at the client workstation. CID allows installation of software at client machines from code residing at a central server, freeing support personnel from the tedious, repetitive, and time-consuming tasks of inserting diskettes and responding to installation dialogs at each client workstation. CID minimizes and often eliminates the need for human intervention at the client machine. To be CID-enabled, products must support: Diskette image transfer The product should have a documented method for storing the images of product diskettes to a hard disk so that the images can be used by both a software distribution manager (SDM), such as NetView DM/2, and the product CID program. Command line parameters A product operation (installation, configuration, and maintenance updates) should be able to be run from the command line with parameters that are defined by the product or program. The SDM uses information entered by an administrator to interface to the product or program at a command line. Redirected drives A CID-enabled product must be able to be installed or updated from any drive or any device that can be represented by a disk drive letter. Products that support being installed or updated only from the A: or B: drives must expand their support to cover any logical drive. Global drive support allows software to be distributed by using file redirection to a code server. Return codes to the SDM A CID-enabled product must be able to pass the status of its installation, configuration, or maintenance processes to a software distribution manager through the use of return codes. CID enablement may also require: Generation of response files Response file support is required if a user dialog is required during a non-CID installation. During a product installation, configuration, or maintenance update, users are typically required to answer questions that affect the outcome of the process. A CID-enabled product operation must be able to access predefined user responses or configure the product operational after installation from a response file (for example, the CONFIG.SYS file updates). Progress information A CID-enabled product should define log files to be used to store information about the progress of the product installation, configuration, or maintenance. These files contain information such as installation, configuration, or maintenance update history and error information. ═══ 9.1.2. Hints for Installation and Distribution ═══ AIX/6000 provides a software management tool called the installp command. Documentation on how to package AIX/6000 applications to use this facility is in the AIX/6000 General Programming Concepts, Vol. 1: Writing Programs. A software distribution product, NetView Distribution Manager (NVDM)/6000, available on AIX/6000 can distribute and install software to AIX/6000, OS/2, DOS, and Windows workstations. For OS/2 and Windows applications, IBM provides Software Installer for OS/2 and Software Installer for Windows. IBM also publishes CID guidelines that describe how to develop an OS/2, DOS, or Windows install program that can be run remotely on an unattended workstation. By following these guidelines, a software developer can produce an application that can be distributed and installed by NVDM/2 or by NVDM/6000. Future Directions POSIX draft standard, P1378.2 Draft 12, March 1994, Software Administration describes software management utilities that will be available in future releases of AIX and OS/2. When the POSIX software administration utilities are available, applications will be able to package software so it can be installed easily and managed consistently. The IBM Software Installer for OS/2 product will provide migration for its application install programs to the POSIX software administration utilities. ═══ 9.2. Configuration ═══ Configuration changes can be made during installation or after installation is complete, either locally or remotely. For more information on configuration-related APIs, see: o LAN Server NetConfig APIs o DCE Configuration APIs ═══ 9.2.1. LAN Server NetConfig APIs ═══ The functions in the Configuration category retrieve network configuration information from the IBMLAN.INI file and are defined as follows: Net32ConfigGet2 Retrieves a single parameter value for a specified network component. Net32ConfigGetAll2 Returns all the parameters for the specified component. The IBMLAN.INI file is an ASCII file containing the configuration information for LAN Server services. User-defined services and applications also store network configuration information in this file. ═══ 9.2.2. DCE Configuration APIs ═══ The DCE configuration APIs return information based on the contents of the local DCE configuration file, which is created during the DCE cell- or machine-configuration process. A configuration file is located on each DCE machine. The file contains the host name, as well as the name of the cell in which the host is located. The configuration APIs can also be used to get additional information corollary to the host name, such as the host principal name and the binding information to the host. The following are the DCE configuration APIs: dce_cf_binding_entry_from_host Returns the host binding entry name. dce_cf_find_name_by_key Returns a string tagged by key. dce_cf_get_cell_name Returns local cell names. dce_cf_get_host_name Returns the hostname relative to the local cell. dce_cf_prin_name_from_host Returns the host principal name. dce_cf_profile_entry_from_host Returns the host profile entry. ═══ 9.3. Network Operating System Management ═══ Network operating system management enables the monitoring and administration of network resources, such as servers, printers, and gateways. For more information, see: o LAN Server Network Management APIs o Hints for NOS Management ═══ 9.3.1. LAN Server Network Management APIs ═══ LAN Server network management APIs enable for local and remote administration of network resources, such as printers, files, serial devices and network services, such as requester, server, and alerter. The following categories of LAN Server APIs provide network management functions: o NetServer o NetService o NetCharDev o NetConnection o NetHandle o NetFile o NetSession o NetShare o NetWksta o HPFS Disk Control o NetUse o NetRemote ═══ 9.3.1.1. NetServer ═══ With the APIs in the Server category, an application can perform remote administrative tasks on a local or remote server. The following APIs are in the Server category: Net32GetDCName Returns the domain controller name associated with a specified domain name. Net32ServerAdminCommand Remotely executes a command on a server. Net32ServerDiskEnum Retrieves a list of disk drivers on a workstation. Net32ServerEnum2 Lists the set of all servers being browsed on the network. The results can be filtered by type or domain. Net32ServerGetInfo Retrieves information about a specified server. Net32ServerSetInfo Changes information about a specified server. ═══ 9.3.1.2. NetService ═══ The functions in the Service category start and control network service programs. A service is a program of any size and function that other applications can use to perform some set of tasks on the network. An application starts and controls the operation of services with the functions in the Service category. The two most important services provided by LAN Server are Requester and Server, which provide the majority of the software required to operate a LAN. When the LAN Server software starts, it in turn starts the Requester service, followed by the Server service. The following APIs are in the Service category: Net32ServiceControl Controls the operations of network services that have been started. Net32ServiceEnum Retrieves information about all started network services. Net32ServiceGetInfo Retrieves information about a particular started network service. Net32ServiceInstall Starts a network service. Net32ServiceStatus Sets status and code information for a network service. ═══ 9.3.1.3. NetCharDev ═══ The NetCharDev APIs control shared serial devices and their associated queues. A character device, also known as a serial device, is a device that performs functions sequentially. This definition is not limited to devices attached to hardware serial ports. The LAN Server software can pool serial devices of the same type into a serial device queue, which a requesting application makes its connection to. A serial device queue can contain one or more serial devices and simultaneously allow multiple applications to connect to one of the available serial devices. Serial device queues can pool serial devices only on a server. Note: Serial device queues exist only while they are being shared. In contrast, a spooled device queue (as for a printer) exists from the time it is created (by calling the appropriate Add function) until the time it is removed. The following APIs are in the Character Device category: Net32CharDevControl Forces a serial device closed when the process that opened the device cannot close it with the DosClose function. Net32CharDevEnum Provides information on all available serial devices pooled in shared serial device queues on a server. Net32CharDevGetInfo Retrieves information about a specified serial device in a shared serial device queue on a server. Net32CharDevQEnum Enumerates all serial device queues on a server. Net32CharDevQGetInfo Retrieves information about a particular serial device queue on a server. Net32CharDevQPurge Deletes all pending requests on a serial device queue. This API only deletes requests that have not been assigned to a device. Net32CharDevQPurgeSelf Deletes all pending requests waiting in a serial device queue that were submitted by a specified computer. Net32CharDevQSetInfo Modifies the state of a serial device queue on a server. ═══ 9.3.1.4. NetConnection ═══ The Net32ConnectionEnum API is the only API of the Connection category. This API lists all connections made to a server by a client or all connections made to a shared resource of a server. A client accesses a shared resource of a server by means of a connection. Thus, a connection is the path between a redirected local device name of a client and a shared resource of a server. ═══ 9.3.1.5. NetHandle ═══ The APIs in this category operate on the handles of remote serial devices and remote named pipes. The Handle category has two APIs: NetHandleGetInfo Retrieves handle-specific information about a serial device or named pipe. NetHandleSetInfo Sets handle-specific information. ═══ 9.3.1.6. NetFile ═══ The APIs in the File category provide a system for monitoring the file, device, and pipe resources that are opened on a server and for closing one of these resources, if necessary. The File category has three APIs: Net32FileGetInfo2 Returns information about a specific opening of a resource. Two levels of detail are available. Level 2 provides the identification number assigned to the resource when it was opened. Level 3 provides additional data about permissions, file locks, and who opened the resource. Net32FileEnum2 Supplies information about some or all open files on the server, allowing the user to supply a key to get the required information through iterated calls to the API. Net32FileClose2 Forces a resource closed when a system error prevents normal closure by the DosClose function. ═══ 9.3.1.7. NetSession ═══ The functions in the Session category control network sessions established between clients and servers. A session is literally a path between a client and a server. A client begins a session with a server the first time the client tries to connect to a shared resource on the server. Any further connections from the client to the other shared resources on the same server do not create another session; multiple connections can be serviced on one session. The Session category contains three APIs: Net32SessionDel Ends a session and deletes all current connections between the client and the server. Net32SessionEnum Returns information about all sessions established with a server. Net32SessionGetInfo Obtains information about a session. ═══ 9.3.1.8. NetShare ═══ The functions in the Share category control shared resources. Share is the term applied to the local device of a server (such as a disk drive, print device, or named pipe) that other applications on the network can access. A unique netname is assigned to each shared resource to enable remote users and applications to refer to the share, rather than the local device name of the share. The following APIs are in the Share category: Net32ShareAdd Adds a share to a server, allowing remote users and applications to access a server resource. Net32ShareCheck Queries whether a server is sharing a device. Net32ShareDel Deletes a netname from the list of shared resources of a server. As a result, all connections to the shared resource are disconnected. Net32ShareEnum Retrieves share information about each shared resource on a server. Net32ShareGetInfo Retrieves information about a particular shared resource on a server. Net32ShareSetInfo Sets the parameters of a shared resource. ═══ 9.3.1.9. NetWksta ═══ The Requester APIs enable applications to control the configuration of a requester. The following APIs are in the Requester category: Net32WkstaGetInfo Returns configuration information about a client. Net32WkstaSetInfo Configures a client. ═══ 9.3.1.10. HPFS Disk Control ═══ The APIs in the High Performance File System (HPFS) Disk Control category control HPFS-related administrative functions, such as Directory Limits. These functions can be implemented for redirected drives for Local Security, if it is installed. These APIs are new for LAN Server 4.0. The following APIs are in the HPFS Disk Control category: HPFS386GetInfo Retrieves information. Net32DASDAdd Invokes the Directory Limits function, which places a limit on the amount of disk space that can be used within a shared-directory tree. Net32DASDCheck Returns the amount of disk space available and the amount already taken in a particular directory tree. Net32DASDCtl Prepares an HPFS386 drive for Directory Limits. Before any other Directory Limits API can be used on a drive, that drive must be enabled for Directory Limits by using either this API, the NETDASD command, or the LAN Requester interface. Net32DASDDel Deletes Directory Limits from a specified directory resource. Net32DASDEnum Returns a list of directories that have had Directory Limits applied to them. This API also returns other related information, such as the limit applied to each directory, the space used, and the space remaining for each directory. Net32DASDGetInfo Retrieves Directory Limits information for a specific resource. Net32DASDSetInfo Sets Directory Limits restrictions on a specific directory resource. ═══ 9.3.1.11. NetUse ═══ The functions in the Use category examine or control connections (uses) between clients and servers. Drives, printers, and serial devices can be redirected to shared resources on servers using the Net32Use APIs. The Net32UseAdd function establishes a connection between a local computer and a resource shared on a server by redirecting a null or local device name to a shared resource on that remote server. The following types of connections can be made: o Device name connections. o Universal naming convention (UNC) connections. In addition to the Net32UseAdd API, the following APIs are part of the Use category: Net32UseDel Ends a connection between a local or UNC device name and a shared resource. Net32UseEnum Lists all current connections between the local workstation and resources on a remote server. Net32UseGetInfo Retrieves information about a connection to a shared resource. ═══ 9.3.1.12. NetRemote ═══ The APIs in the Remote Utility category enable applications to copy and move remote files, run a program remotely, and access the time-of-day information on a remote server. The following APIs in the Remote Utility category relate to file system functions: Net32RemoteCopy Performs optimized file copying. Files on a remote server are copied without physically moving the files to and from the local client. The source and destination must be on the same server. Net32RemoteMove If the source and destination are on the same drive, moves files or directories from one location to another on a remote server without physically moving the data. If the source and destination are on different drives, the move does not require shuffling the data to and from the local client. ═══ 9.3.2. Hints for NOS Management ═══ LAN NetView and NetView/6000 provide remote management of network as well as system resources through the use of the simple network management protocol (SNMP). Operating system and machine resources are being created using the host resource management information base (MIB) (RFC-1514 of Internet Engineering Task Force). Applications can also be managed by LAN Netview and NetView/6000 by writing subagents that instrument enterprise-specific application MIBs to these management applications. Either LAN NetView or NetView/6000 can be the managing system for the network. Applications that run on OS/2, AIX/6000, DOS, or any system that provides a TCP/IP protocol stack and an SNMP agent can be managed by these applications. AIX/6000 provides the SNMP multiplexing protocol (SMUX) to allow an application to create subagents to the system MIB. OS/2 TCP/IP Version 2.0 provides the distributed program interface (DPI) for OS/2 applications to similarly enable resources for remote management. Future Directions o Communications protocols supported by SNMP agents will be expanded to include NetBIOS, IPX, and SNA transports. This will allow applications with SNMP agents to be managed in these additional environments. o The desktop management task force (DMTF) desktop management interface (DMI) will be provided for application instrumentation. This will allow the application developer to write to the DMI and not have to construct an SNMP subagent. o The X/Open proposed Object Management Framework will be available and managed object base classes will be defined for remote system management. Applications will be able to subclass these managed object base classes to create their own managed object classes. For example, the mailserver objects for people and destinations could be monitored and managed from a management application that uses distributed SOM. This will allow applications to easily enable objects for management and will provide a consistent object view of the network and all the systems and resources for the administrator. o The LAN Server NOS APIs will be maintained for backward compatability with existing LAN Server environments. ═══ 9.4. Reliability/Availability/Serviceability ═══ RAS refers to reliability, availability and serviceability. The reliability is the ability of a system to recover from detected errors and to avoid an unrecoverable error. Availability is how often a functional unit or applications can used when required. Serviceability is the ability to identify and repair system failures in the least amount of time with the least disruption to the customer operation. For more information, see LAN Server RAS APIs. ═══ 9.4.1. LAN Server RAS APIs ═══ The following APIs should be used for accessing LAN server log information. o NetStatistics o NetErrorLog ═══ 9.4.1.1. NetStatistics ═══ LAN Server accumulates operating statistics for requesters and servers from the time that a Requester or Server service is started. The Net32StatisticsGet2 API retrieves these statistics and can optionally clear the statistics. ═══ 9.4.1.2. NetErrorLog ═══ The functions in the Error Logging category control the error log file, which contains information about the following types of errors: o LAN Server software internal errors o OS/2 internal errors o Network service errors Error log entries are stored as ASCII text. The default error log file name is \IBMLAN\LOGS\NET.ERR. All error logging APIs perform their operations on this file. When FFST/2 support is active, selected LAN Server error log entries are also sent to FFST/2 for logging in the OS/2 error log. The following APIs are part of the Error Logging category: Net32ErrorLogClear Clears (and optionally saves) the error log file of a computer. Net32ErrorLogRead Reads from a specified computer error log. Net32ErrorLogWrite Writes an entry file to the error log file of a local computer. ═══ 9.5. Licensing ═══ Licensing is the runtime enforcement of a selected license policy using electronic keys for software execution control, asset management, and protection of intellectual rights. The APIs associated with licensing are currently not available in the LAN Systems Toolkit. For more information on licensing, see iFOR/LS. ═══ 9.5.1. iFOR/LS ═══ iFOR/LS is a license manager product that implements technical licensing technology. iFOR/LS is a new architecture based on NetLS, which is becoming an industry standard. iFOR/LS has been chosen as the OSF licensing technology and is either used by or has been selected as a standard by IBM (AIX and OS/2), Hewlett Packard (HP/UX), and Novell (NetWare). iFOR/LS code is embedded in the client application, the remote service (in this case, the iFOR/LS license server), and the location-broker system. All three are transparent to end users in a properly configured system. Application developers use the iFOR/LS application developer's toolkit administrator runtime kit (ARK) for AIX to install and maintain the license server and the location broker system.