OS/2 Shareware BBS: 10 Tools/10-Tools.zip/lanapirm.zip/LANAPIRM.INF

OS/2 Help File | 1995-04-20 | 179KB | 4,835 lines

ΓòÉΓòÉΓòÉ <hidden> 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.