OS/2 Shareware BBS: 8 Other/08-Other.zip/lasysapi.zip/SIMPMAST.INF

OS/2 Help File | 1995-04-20 | 291KB | 4,844 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, referenced in this document, are trademarks of the IBM
Corporation in the United States, other countries, or both:

AIX
AIX/6000
AIXwindows
Anynet
Anynet/2
BookManager
BookMaster
C Set++
C Set/2
CD Showcase
CICS
CM/2
Common User Access
CPI-C
CUA
DB/2
DDE
Direct to SOM
FFST/2
FlowMark
IBM
iFOR/LS
InfoExplorer
IPF
IPF/X
IPF/Win
LAD/2
LAN NetView
LAN NetView Monitor
MQSeries
NetSP
NetViewDM/2
NetView/6000
NetViewDM/6000
Operating System/2
OS/2
Person-to-Person/2
Presentation Manager
PS/2
RISC System/6000
SNA
SOM
SOMobjects
SPM/2
SQL
System Object Model
Time and Place/2
Workplace Shell

The following terms, referenced inthis document, are trademarks of other
companies as follows:

Trademarked Terms:             Trademark Owner:
ArborText                      ArborText, Inc.
ATT                            American Telephone  Telegraph Company
Borland C++                    Borland International, Inc.
CorelDraw!                     Corel
DCE                            Open Software Foundation, Inc.
DEC                            Digital Equipment Corporation
DOS                            Microsoft Corporation
Encina                         Transarc Corporation
HP                             Hewlett-Packard Company
InterLeaf                      Interleaf, Inc.
Kerberos                       Massachusetts Institute of Technology
Macintosh                      Apple Computer, Inc.
Motif                          Open Software Foundation, Inc.
NetLS                          Hewlett-Packard Company
Network Computing System (NCS) Hewlett-Packard Company
Netware                        Novell, Inc.
Network File System (NFS)      Sun Microsystems, Inc.
OLE                            Microsoft Corporation
Open Software Foundation (OSF) Open Software Foundation, Inc.
Open Network Computing         Sun Microsystems, Inc.
OSF/DCE                        Open Software Foundation, Inc.
OSF/Motif                      Open Software Foundation, Inc.
OpenVision                     OpenDoc
Component Integration Laboratories Hewlett-Packard Company
Palladium                      Massachusetts Institute of Technology
POSIX                          Institute of Electrical and Electronics
                               Engineers, Inc. (IEEE)
PostScript                     Adobe Systems, Inc.
RPC                            Sun Microsystems, Inc.
RTF                            Microsoft Corporation
SGML                           ISO Standard
SoftQuad Author/Editor         SoftQuad, Inc.
SunSoft (Sun)                  Sun Microsystems, Inc.
Taligent                       Taligent
UNIX                           UNIX System Laboratories, Inc.
Windows                        Microsoft Corporation
X/Open                         X/Open Company Limited, U.K.


ΓòÉΓòÉΓòÉ 2. Preface ΓòÉΓòÉΓòÉ

Why the Focus on LAN Systems?

What This Roadmap Covers

What Are the Guidelines For?


ΓòÉΓòÉΓòÉ 2.1. Why the Focus on LAN Systems? ΓòÉΓòÉΓòÉ

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. What This Roadmap Covers ΓòÉΓòÉΓòÉ

Today's IBM LAN systems products provide a wide array of functionality to solve
your business need:

o   OS/2 provides reliable client software that supports multiple hardware and
    software environments.
o   AIX/6000 provides workstations access to data across heterogeneous systems
    including LANs, minicomputers, and mainframe hosts.
o   OS/2 LAN Server transforms OS/2 into a full-fledged Network Operating
    System.
o   Network Transport Services/2 and the AnyNet product family provide
    connection flexibility.
o   Advanced Server for Workgroups, Lotus Notes, and Lotus cc:Mail support
    workgroup computing.
o   LAN Distance lets you bring your LAN on the road.
o   Communications Manager/2 provides an "all-in-one" subsystem for
    communcating among networks.
o   The DB2 product family, the Distributed Database Connection Services
    product family, the LAN Resource Extension Services for VM and MVS, and LAN
    Server for VM and VMS provide easy access to host data.
o   The LAN Netview product family provides comprehensive system management.
o   The Distributed Computing Environment (DCE) and the System Object Model
    (SOM) extend today's products to the distributed objects of the future.

Together, the LAN Systems APIs allow an application developer to take advantage
of and manage every aspect of the single system image provided by the LAN
Systems products.  In this roadmap, the LAN Systems API implementation
guidelines are categorized by the functionality they provide:

Base Operating System APIs are generally specific to the local operating system
and manage resources that are not distributed.  However, a few guidelines are
appropriate to ensure application portability, network- wide time
synchronization and internationalization.

Security APIs provide for user registration, mutual authentication of clients
and servers, access control restrictions and auditing of security-related
events. Guidelines ensure you can take advantage of the security single system
image.

Interprocess Communication (IPC) APIs provide mechanisms for parts of a
distributed application or resource manager to talke to each other.  Guidelines
help you determine the best communication mechanism for your application needs.

Inter-Application Collaboration (IAC) for Compound Documents provides for
interapplication collaboration.

Tranport APIs provide reliable end-to-end communications across Wide Area
Networks (WANs) and Local Area Networks (LANs) across various protocols, such
as NetBIOS, TCP/IP, IPX/SPX, etc. Guidelines let you take advantage of
transport independent APIs.

System Management APIs provide a way to manage both local and remote systems.
Guidelines ensure you can take advantage of the key features of system
management, such as RAS, software management, license management, performance
monitoring, and remote system management.

Extended Operating System APIs provide functionality that extend base operating
system specific functions across a network, such as printing or provide
additional functionality in a network environment, such as mail. Guidelines
ensure you can take advantage of the single system image.

Development Tool Delivery  outlines the development tool delivery strategy and
mechanism using The Developer Connection for LAN Systems.

Customer Information  provides guidelines for design and content of customer
information and associated tools that can be used.

Usability provides guidelines for application installation, configuration, and
user interface.

Note:  For more information about specific APIs or IBM's API strategy, see the
LAN Systems API Roadmap on The Developer Connection for LAN Systems CD-ROM.


ΓòÉΓòÉΓòÉ 2.3. What Are the Guidelines For? ΓòÉΓòÉΓòÉ

These guidelines outline the best route to take advantage of the LAN as a
system when designing applications.  Use of the guidelines will help you to
make the underlying distributed services transparent to your users and
administrators, ensure your application integrates easily into this complex
environment, ensure application portability across platforms, and better
prepare your application for future technology developments.


ΓòÉΓòÉΓòÉ 3. Base Operating System ΓòÉΓòÉΓòÉ

Application Portability

Time

Internationalization (I18N)


ΓòÉΓòÉΓòÉ 3.1. Application Portability ΓòÉΓòÉΓòÉ

The goal of application portability is to minimize additional work for
application developers as the environment in which those applications run
evolves. Application portability comes in two types:  (1) source compatibility,
and (2) binary compatibility.  Source compatibility means that the source code
is generally portable across multiple operating systems with little or no
change; i.e. only re-compilation, re-linking, re-building types of activity.
Binary compatibility means that the current application binary code can run
as-is on multiple versions of an operating system.


ΓòÉΓòÉΓòÉ 3.1.1. Operating System Services ΓòÉΓòÉΓòÉ

Writing applications involves not only the use of APIs defined in this roadmap,
but the use of operating system services and interfaces as well. Use of
standard operating system services and interfaces increases portability of
applications. These operating system services and interfaces can be specific to
that operating system or a class of operating systems.  A class of operating
systems, for example, could be the set of DOS, Windows, and OS/2. Unix-based
operating systems such as AIX, HP/UX, Solaris, and OSF/1 are another class of
operating systems. Operating systems can also provide their services and
interfaces based on well-recognized international standards. An example of a
set of system services and interfaces specific to an operating system would be
the OS/2 threads for the OS/2 operating system. Examples of well-recognized
international standards for system services and interfaces independent of
operating system are POSIX 1003.1 for system services and interfaces (except
for process model) and POSIX 1003.4a for threads.


ΓòÉΓòÉΓòÉ 3.1.2. Standards ΓòÉΓòÉΓòÉ

Standards can aid the application developer in application portability. A
standard may be anything which has sufficiently widespread industry acceptance.
Standards can be viewed in two forms:

o   formal standards created by standards organizations

o   accepted industry standards created by the marketplace (e.g. companies and
    consortiums)

Both types of standards are recommended in this document.  Examples of formal
standards are the POSIX system services and interfaces from IEEE (Institute of
Electrical and Electronic Engineers) and the DCE (Distributed Computing
Environment) from X/Open.  Examples of accepted industry standards are the DOS
APIs and the LAN Server APIs.


ΓòÉΓòÉΓòÉ 3.1.3. Object Management Interfaces and Services ΓòÉΓòÉΓòÉ

For an object-oriented programming model, IBM provides the System Object
Model/Distributed System Object Model (SOM/DSOM). In addition to all the
benefits of object-oriented programming, like encapsulation,
multiple-inheritance, and polymorphism, it provides the following to
application developers:

o   language neutrality

o   dynamic binding

o   location-transparent access to distributed objects

o   persistence, replication, collection, emitter frameworks


ΓòÉΓòÉΓòÉ 3.1.3.1. SOM/DSOM ΓòÉΓòÉΓòÉ

Distributed SOM is the distributed object programming model and is compliant
with OMG's CORBA specification for object request brokers.  By using SOM's
CORBA-compliant IDL (InterfaceDefinition Language), application developers get
portable interfaces, language-neutrality, and transparent distributed object
access. DSOM presents the clients with proxy objects of the remote objects,
which can be used like local objects. DSOM can use existing SOM objects
transparently.

There are various granularities at which you can apply object-oriented
techniques. For example, at the SOM-object level, SOM/DSOM addresses the three
main aspects of object-oriented systems design:

o   object model: identities and structures of objects (SOM objects)

o   dynamic model: interactions among objects (passing message/methods)

o   functional model: transformations inside an object (state transition)


ΓòÉΓòÉΓòÉ 3.1.3.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 (may include
class objects) which:

o   serves as a unit (object model) and

o   with external interfaces, (dynamic model) and

o   with internal interfaces, (functional model).

In a framework, the single component itself may be distributed across the
network and developers should make sure 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 Object Request Broker (ORB); the location and
    implementation of the object are hidden from the client and the client
    accesses the object as if 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++ 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 get 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++ code, and SOM's Emitter framework can
generate bindings from multiple languages. Also, Microsoft-COM emitter for SOM
is available: application developers building applications on SOM/DSOM can use
it to achieve SOM-COM interoperability.


ΓòÉΓòÉΓòÉ 3.1.3.3. Supported Platforms ΓòÉΓòÉΓòÉ

SOM/DSOM will be available on all major IBM platforms and some other industry
platforms. Today, it is available on AIX/6000, OS/2, and Windows.


ΓòÉΓòÉΓòÉ 3.1.4. Application Portability Guidelines ΓòÉΓòÉΓòÉ

The following guidelines will help to increase application portability in this
environment.

1.  Use the guidelines for each service discussed in this document.

2.  Use 32-bit APIs; support for 16-bit APIs is diminishing.

3.  Use the operating system services and interfaces that best meet your
    application portability environment.

    Portability across classes of operating systems:  use those operating
    system services and interfaces that are common across classes of operating
    systems. For example, X/Open Specification 1170 defines APIs that are in
    wide use across applications and operating systems.

    Portability within a class of operating systems:  use those operating
    system services and interfaces that are common within that class of
    operating system. For example, POSIX 1003.1 APIs are common across Unix
    operating systems.

4.  Write your application programs in a language portable across operating
    systems and hardware platforms.  The ANSI C language is one such example.
    An assembler language is an example of what not to use to write portable
    applications.

5.  Use SOM as the object-oriented programming model.

    Application developers should try to use the SOM-based frameworks and
    classes rather than implementing similar functionality themselves.
    Application developers are encouraged to write more specialized and
    modularized component applications that can participate in this
    collaboration environment.

6.  Isolate access to system-specific APIs to as few places as possible within
    your application.


ΓòÉΓòÉΓòÉ 3.2. Time ΓòÉΓòÉΓòÉ

Time means date, time of day in hours, minutes, and seconds down to some
granularity that may be less than seconds, timezone, and daylight savings time
state.  Each operating system generally has its own time API and time service.
Single system image for time means that each system that participates in
network-wide clock synchronization sees the same time.  The clock
synchronization provided by the time service enables distributed computing
applications to use timestamps for operations such as event sequencing,
duration, and scheduling. Since a distributed system may span several time
zones, applications need a standard time representation for calculations and
should convert to local time only for display purposes.


ΓòÉΓòÉΓòÉ 3.2.1. Time Interfaces and Services ΓòÉΓòÉΓòÉ

Time-dependent applications in a distributed single system image need access to
a network-wide synchronized clock.  A number of time services and interfaces
are available in this environment to assist the programmer in exploiting time
and timestamps in applications. The figure illustrates the general structure of
these services.

In the figure, the following terms are associated with the time technical
model.

Object: clock

Service: time operations

APIs: time service APIs

Service Provider: time service

There are four aspects of the time interface/service from the application
developer's viewpoint.

o   An application uses the time interface to obtain time.

o   An application may change the timezone information and have the changed
    timezone information apply to itself.

o   An application uses the time interface to do timestamp operations such as
    manipulations, conversions, comparisons, and calculations.

o   The customer may choose to add an external time source, such as an atomic
    clock, in the network and may write a program to do this device to the
    network time synchronization - the program is written using an external
    time provider interface.


ΓòÉΓòÉΓòÉ 3.2.2. Time Guidelines ΓòÉΓòÉΓòÉ

Get Time Information

Convert Time Information

Manipulate Time Information

Set Time Information

Year 2000 Clean

Timestamp Content

Time Presentation


ΓòÉΓòÉΓòÉ 3.2.2.1. Get Time Information Guidelines ΓòÉΓòÉΓòÉ

Applications use time for a variety of reasons, such as timestamped entries in
a log file, and hence have a need to obtain time from the system. Getting time
means getting date, time, timezone information, and daylight savings time
state.  Some operating systems have operating system specific interfaces for
obtaining time; others use standard interfaces. Applications that need time
information that is valid in a network environment should not base timestamps
on "local system time", but rather on standard timestamps.

1.  (LAN Server) Use the LAN Server NetRemoteTOD API to obtain time from the
    domain controller or any LAN server.

2.  (DCE) Use X/Open DCE APIs to obtain time information.  Applications should
    use the X/Open DCE:  Time Services Preliminary Specification for these time
    functions.

3.  (Other) Use POSIX or X/Open Specification 1170 APIs to obtain time
    information.


ΓòÉΓòÉΓòÉ 3.2.2.2. Convert Time Information Guidelines ΓòÉΓòÉΓòÉ

Time is typically returned in a structure and the content and format of that
structure varies by the interface invoked to obtain time. Interfaces are
available that convert between these binary timestamps that use different time
structures.  Examples of available conversions are:

o   between POSIX and DCE binary timestamps (tm struct and utc struct)
o   between the DCE binary representations (utc struct and timespec struct)
o   between a binary time stamp and its ASCII representation

1.  (DCE) The application uses X/Open DCE APIs to convert time information.
    Applications should use the X/Open DCE: Time Services Preliminary
    Specification for these time functions.

2.  (Other) The application uses POSIX or X/Open Specification 1170 APIs to
    convert time information.


ΓòÉΓòÉΓòÉ 3.2.2.3. Manipulate Time Information Guidelines ΓòÉΓòÉΓòÉ

These are interfaces that allow an application to compare binary timestamps, do
calculations between two binary timestamps such as add or subtract, and
manipulate binary timestamps to establish a time range.

1.  (DCE) Use X/Open DCE APIs to manipulate time information. Application
    should use the X/Open DCE:  Time Services Preliminary Specification for
    these time functions.

2.  (Other) Use POSIX or X/Open Specification 1170 APIs to mainpulate time
    information.


ΓòÉΓòÉΓòÉ 3.2.2.4. Set Time Information Guidelines ΓòÉΓòÉΓòÉ

In general, an application does not have the need to set the time. However, one
example of this is to change timezone information - the TZ environment variable
in POSIX and X/Open Specification 1170 and the utc_* interfaces in X/Open DCE
provide this capability.  The X/Open DCE provides a superset of the POSIX
timezone rules for more granularity.  Another example is an application that is
written to add an external time source to the systems network time
synchronization.  That application is written using the X/Open DCE time
provider interface.

1.  (DCE) Use X/Open DCE APIs to set time information.  Applications should use
    the X/Open DCE:  Time Services Preliminary Specification for these time
    functions.

2.  (Other) Use POSIX or X/Open Specification 1170 APIs to set time
    information.


ΓòÉΓòÉΓòÉ 3.2.2.5. Year 2000 Clean Guidelines ΓòÉΓòÉΓòÉ

Clean applications which manipulate time outside of supplied interfaces should
ensure that dates before the year 2000, the year 2000 itself, and after the
year 2000 are handled correctly.


ΓòÉΓòÉΓòÉ 3.2.2.6. Timestamp Content Guidelines ΓòÉΓòÉΓòÉ

Timestamps should always contain at least the following information: date,
time, daylight savings time status, and timezone.


ΓòÉΓòÉΓòÉ 3.2.2.7. Time Presentation Guidelines ΓòÉΓòÉΓòÉ

Timestamps should be converted to the appropriate time zone and cultural format
for presentation to users.  XPG/4 APIs are used to accomplish the correct
presentation.  See Culture-specific Information Guidelines for
internationalization of the time format presentation.


ΓòÉΓòÉΓòÉ 3.3. Internationalization ΓòÉΓòÉΓòÉ

Internationalization (commonly abbreviated as I18N) of applications consists of
the ability to support such things 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.

The goal of internationalization is to produce a single worldwide product with
a single binary image that is usable by a customer who is from any culture and
who possibly speaks a different language from the language of the application
developer, possibly in a world-wide context of multiple countries, languages,
and cultures.

A Worldwide Product includes all character and string handling, as well as
support for culture-specific formatting such as time and date and for
culture-sensitive collation. It should be achieved regardless of whether the
product is ever translated (for example, from English into another language).

The major aspects of internationalization are:

1.  Code-set independence (CSI)

    Code-set independence means that the application does not rely on knowledge
    of a specific code set, or on knowledge of how many bytes represent a
    character.

    Programming the CSI aspect also results in enabling character and string
    handling for SBCS (single-byte character Set), DBCS (double-byte character
    set), and MBCS (multi-byte character set) support.

2.  Culture-specific information (locale support)

    Culture-specific information includes time and date, numeric, and monetary
    formats, as well as collation.  Such information is kept in a locale path
    (combined language and territory/country information) that is named
    according to each specific locale, and configured in the user's environment
    variables. Programming for locale support ensures that cultural formatting
    can be adapted to the customs of the user.

3.  User-visible Text (messaging)

    Messages and other user-visible items such as icons are isolated from the
    application code and handled in a standardized way. Internationalizing
    user-visible text not only provides the capability to switch languages, but
    also provides the capability to translate more easily.

4.  Conversion of code sets or character sets

    In a heterogeneous code-set environment, it is necessary to convert a
    character from one code set to another in order to preserve data integrity.
    Conversion APIs are called by the application.


ΓòÉΓòÉΓòÉ 3.3.1. Internationalization APIs and Services ΓòÉΓòÉΓòÉ

This section addresses today's National Language Support (NLS) environment and
what lies in the future for the application developer. NLS includes both
internationalization and localization (commonly abbreviated as L10N -- the
specific country information for cultural formatting and the translated version
of user-visible text). Each operating system, present and moving into the
future, provides a solution and a set of APIs for each of the major aspects of
internationalization:  code-set independence, culture-specific information,
user-visible text, and code-set conversion. Operating system-specific
solutions, however, are converging toward a solution that can be applied across
operating systems.


ΓòÉΓòÉΓòÉ 3.3.1.1. Today ΓòÉΓòÉΓòÉ

OS/2 applications today use either a set of family APIs to get language,
country, keyboard and code set information according to the user's
configuration in CONFIG.SYS, or applications use a set of OS/2 Presentation
Manager (PM) APIs (Prf*) to obtain culture-specific information from the .ini
file that has been configured during installation or by making a selection on
the OS/2 Country Settings notebook behind the OS/2 WorkPlace Shell System Setup
folder.

AIX/6000 applications use a library of XPG/4 I18N APIs that access the locale
on the path that has been configured as an environment variable.

As a step toward converging the programming model across operating systems, and
therefore across distributed systems, The Developer Connection for OS/2 CDROM
provides a library of XPG/4 I18N APIs and locales for OS/2. This set of APIs
provides access to locales that meet current cultural standards for the
supported countries. The XPG/4 conversion APIs iconv_open(), iconv() and
iconv_close() will be supported on each operating system to manage code set
conversion in a code-set heterogeneous environment. Applications are then able
to handle the major aspects of I18N programming in the same way, using the same
set of XPG/4 I18N APIs for each of the operating systems:  OS/2 and AIX/6000.

Today, only data from a single code set at one time is supported in the LAN
environment by machines that share resources with each other.  Many different
code sets are supported, but the LAN environment must be homogeneous in order
to retain accurate data representation.  OS/2 and AIX/6000 on the same LAN must
be configured for the same code sets in order for data beyond 7-bit ASCII to be
exchanged correctly.


ΓòÉΓòÉΓòÉ 3.3.1.2. Future ΓòÉΓòÉΓòÉ

To provide support for all the world's major published languages within a
single session, ISO 10646 UCS-2 (Unicode) will be supported in the XPG/4 I18N
model via locales that are encoded according to a scheme called the Universal
Transfer Format based on 8 bits (UTF-8). UTF-8 was adopted by X/Open and
originally called "File-system Safe" because it includes no null bytes, which
signal End of File on the UNIX file system. The encoding scheme uses one to six
bytes to represent a character. Unicode and ISO 10646 UCS-2 provide the world's
major publishable characters in a single 64K-code set that has been established
by ISO standards. The encoding scheme uses two bytes to represent a basic
character and uses extensions to create composite characters. The large size of
the unicode character set allows it to support the scripts of the world's major
languages.

A programming model with APIs is needed to support ISO 10646 UCS-2 as well as
to support multithreading. Supporting locales on multiple threads at the same
time requires the capability of switching locale context.  Special APIs that
specify a locale handle have been proposed for future support of locale-context
switching.
Such use of the locale handle prevents the global setlocale() from affecting
any other threads of the same session.
Extensions will be developed to the XPG/4 model to support both ISO 10646 UCS-2
and multithreading.


ΓòÉΓòÉΓòÉ 3.3.2. Internationalization Guidelines ΓòÉΓòÉΓòÉ

Applications should be written to the X/Open Portability Guide Issue 4 (XPG/4)
I18N programming model. AIX/6000 already provides the XPG/4 APIs in the I18N
library, and for OS/2, the library is provided on The Developer Connection for
OS/2  CDROM. The XPG/4 I18N programming model uses the setlocale() API at the
beginning, and is followed by the appropriate XPG/4 I18N API according to the
four aspects of I18N: code-set independence, culture-specific information,
user-visible text, and conversion of code sets.

Using setlocale() and the appropriate XPG/4 I18N API results in isolating
culture-specific information from the application code. An application can
compile only the application code and manage separately the localization for
each locale. Instead of building, testing, and shipping n different versions of
the code, the application developer can build, test, and ship a single version
of the application code and n smaller versions of only the culture-dependent
information that can be accessed at run-time according to the user's
configuration.

The following guidelines define how to achieve a worldwide product with the
major aspects of interationalization:

Code-set Independence (CSI)

Culture-specific information (locale support)

User-visible text

Conversion of code sets or code pages

Internationalizing icons


ΓòÉΓòÉΓòÉ 3.3.2.1. Code-set Independence (CSI) Guidelines ΓòÉΓòÉΓòÉ

The need that has been solved by CSI has also been expressed as DBCS
(double-byte character set) enabling and MBCS (multi-byte character set)
enabling. The solution handles strings or characters without making assumptions
as to which coded character set the characters come from, or which encoding the
characters have.

Using the XPG/4 model for code-set independence provides a way for the
applicaton to support all of the locales that are provided by the operating
system as well as any properly user-defined locale.


ΓòÉΓòÉΓòÉ 3.3.2.2. Culture-specific Information Guidelines ΓòÉΓòÉΓòÉ

Culture-specific information is supported by the XPG/4 APIs. The XPG/4 I18N
provides the locale and API support for the following:

o   Time and date format
o   Monetary format
o   Numeric format
o   Cultural collation

Using the XPG/4 model for culture-specific information provides a way for the
application to support all of the locales that are provided by the operating
system.


ΓòÉΓòÉΓòÉ 3.3.2.3. User-visible Text Guidelines ΓòÉΓòÉΓòÉ

It is important that user-visible text be isolated from the source code text.
For information about displaying text through GUIs, see the Graphical User
Interface section. For guidelines on composing user-visible text (usually
English) so that it is correct and translatable, see the Customer Information
section.

For a model that is portable across OS/2 and AIX/6000, messaging should handled
according to the XPG/4 I18N standard.

Not all user-visible text should be translated. Examples include:

o   Command names, API verb names, path names, and executable program names
o   Environment variables
o   Reserved device names (e.g. MOUSE, POINTER, SCRN, PRN, LPT1-3, COM1-2)
o   Font family names and type names
o   Extended Attribute (EA) content and EA keywords (e.g. .CODEPAGE=)
o   Hypertext links
o   Control information that points to any of the above


ΓòÉΓòÉΓòÉ 3.3.2.4. Code-set Conversion Guidelines ΓòÉΓòÉΓòÉ

The XPG/4 model provides a set of APIs to handle conversions from one code set
to another.  Such conversions should be used to manage interchange of data on a
code-set heterogeneous system.  IBM provides mappings that have been
implemented in the conversion tables. If the mappings used are not coordinated,
the application runs the risk of not being able to interoperate properly with
IBM systems and other standard systems, and data cannot be interchanged with
consistency.


ΓòÉΓòÉΓòÉ 3.3.2.5. Internationalizing Icons Guidelines ΓòÉΓòÉΓòÉ

In order to avoid offending people of any culture with inappropriate icons,
providing an icon that is not understandable in another culture, or colliding
with an existing product logo in any country, icons should be
internationalized.

1.  Icons can be substituted by the country as appropriate and stored according
    to the XPG/4 locale path name.

2.  Icons are not bound into the executable.  They are provided in separate
    resource files.

3.  Icons do not contain text of any kind.


ΓòÉΓòÉΓòÉ 4. Security ΓòÉΓòÉΓòÉ

Many customers require that the security single system image should be a
Distributed C2 Single System Image: the whole collection of hardware and
software in a customer's enterprise should be configurable to look to its users
like a single system which meets (and in some selected areas exceeds) the US
Government TCSEC ("Orange Book") C2 (commercial) security requirements.

In general terms, the C2 requirements state:

o   The system should identify all system users uniquely and authenticate their
    identities before allowing them access to any system resources
    (authentication).

o   The system should enable users to restrict access to resources they own by
    specifying allowable accesses for each system user (authorization). In
    networked configurations, restricting access to resources may require use
    of message protection services. These services protect information flowing
    across network links from unauthorized modification and/or examination.

o   The system should irrevocably destroy information in all deleted resources
    (object reuse protection).

o   The system should keep a tamper-resistant audit log of security-relevant
    events, which can be examined for evidence of attacks on the system's
    security (audit). See "Trusted Computer System Evaluation Criteria",
    protection class C2, for information about what events should be considered
    security-relevant.

Note:  Complying with the security guidelines in this document will not (by
       itself) insure that compliant applications or the environments in which
       they run will conform to all C2 criteria. (C2 criteria require that all
       components of a system, including hardware, be evaluated as an integral
       whole; furthermore, C2 criteria include documentation and development
       process assurance requirements not addressed in this document.)

The Single System Image requirement further implies that:

o   Users should be able to gain access to all resources on the system through
    a single logon (i.e. a single presentation of a username and password to
    the system), regardless of where in the system the resources are stored and
    which resource manager protects them.

o   Users should be able to change passwords from any computer in the system
    and be assured that the new password will be valid for logon at  all
    machines in the network shortly after such a change.

o   Users and administrators should be able to administer access permission
    information for all resources they own regardless of where in the system
    those resources are stored and which resource manager protects them.

o   System administrators should be able to administer users and policy in a
    single logical database through a single interface.


ΓòÉΓòÉΓòÉ 4.1. Security Interfaces and Services ΓòÉΓòÉΓòÉ

A number of security services and interfaces are available in this environment
to assist the programmer in producing secure, manageable applications.

Security interfaces and services include:

User management

Local security context management

Network authentication

Authorization

Security auditing


ΓòÉΓòÉΓòÉ 4.1.1. Supported Platforms ΓòÉΓòÉΓòÉ

Today's LAN Server and DCE offerings provide APIs for management of user
information, user logon, secure session establishment, management of
authorization information, and authorization checking (see below). AIX/6000 3.0
and above provide APIs for recording security audit information. Applications
in today's environment should be written to use the APIs of the operating
system and network services available; in this environment possible operating
systems include Windows (perhaps with third-party security services installed),
OS/2, and AIX/6000.

In the future, applications will be able to access network security services
through a set of generic interfaces as shown below. User information will be
manageable through a User Registry Framework API.


ΓòÉΓòÉΓòÉ 4.1.2. User Management ΓòÉΓòÉΓòÉ

User information includes:

o   user definitions
o   group memberships
o   passwords
o   password composition rules
o   password expiration intervals
o   credential expiration intervals
o   logon hours
o   workstation logon restrictions


ΓòÉΓòÉΓòÉ 4.1.3. Local Security Context Management ΓòÉΓòÉΓòÉ

Local Security Context Management services allow applications to discover (
and, in the case of trusted applications, to change) the user identity
associated with operating system processes and threads. Different operating
systems typically have different Local Security Context Management services and
interfaces. The AIX/6000 local security context management API is the POSIX
1003.1 (getuid(), getgrp(), setuid(), etc...) family of interfaces.

Future releases of OS/2 will have a Security Context Services API for local
security context management.


ΓòÉΓòÉΓòÉ 4.1.4. Network Authentication ΓòÉΓòÉΓòÉ

Secure association services provide applications with location- transparent,
secure inter-process communication mechanisms. Applications which take
advantage of secure association services need to be only minimally
"security-aware"; they need not implement any security functions themselves.

The DCE Authenticated RPC service is the first (and currently the only)
available secure association service in this environment. In the future, a
Secure Conversation Service (exposing the CPIC interface) and a Secure Message
Queueing Service also will be implemented.

Applications that cannot use an existing secure association service in the
future will be able to protect data transmitted over networks by using network
security context and message protection services through the GSSAPI. Using
GSSAPI requires slightly more security awareness than using a secure
association service, but is significantly easier and safer than implementing
network security protocols in application code.

GSSAPI provides the following functions:

o   Network Authentication (Allows application clients (acting on behalf of
    users) and remote resource managers to authenticate one another's
    identities).
o   Network Security Context Management (Allows users and remote resource
    managers to build "secure connections" on top of insecure transport or
    association services).
o   Message Protection (Allows applications to protect the integrity and
    privacy of data which flows on network links).

Various authentication, security context management, and message protection
services will be available through GSSAPI; the recommended authentication
service will be DCE. If other authentication services are used, some
authorization and delegation functionality may not be available. The
recommended authorization credential format will be the DCE Privilege Attribute
Certificate (PAC). OSF/DCE 1.1 will provide an "Extended PAC" (EPAC) which will
be usable by applications requiring authorization information other than DCE
user and group identities.


ΓòÉΓòÉΓòÉ 4.1.5. Authorization ΓòÉΓòÉΓòÉ

The OS/2 LAN Server provides the NetAccess* APIs for management of
authorization information. AIX versions 3.0 and above provide an access control
interface which can be used to protect AIX files which are accessed locally, or
from remote AIX clients through the NFS filesystem.

DCE provides the sec_acl* authorization interface; future versions of DCE will
provide an access control library which will allow applications to use this API
to manage their own authorization information.

The sec_acl* API will be the recommended interface for management and checking
of authorization information in the future.


ΓòÉΓòÉΓòÉ 4.1.6. Security Auditing ΓòÉΓòÉΓòÉ

AIX versions 3.0 and above provide an API for recording security audit
information.

Future versions of DCE will provide a security auditing API and service, which
applications will be able to use to record security audit information. This API
will be based on the forthcoming POSIX security auditing standard and will be
the recommended interface when it becomes available.


ΓòÉΓòÉΓòÉ 4.2. Security Guidelines ΓòÉΓòÉΓòÉ

Integrated logon

Integrated user management

User names and passwords

Integrated authorization policy management

Identified operations

Authorized access

Audit

Message protection

Object reuse protection


ΓòÉΓòÉΓòÉ 4.2.1. Integrated Logon Guidelines ΓòÉΓòÉΓòÉ

Applications should take advantage of the Local Logon and Local and Network
Security Context Management facilities of the system to avoid asking a user who
has already logged on to present his password again. When running in this
environment, the application always uses identity information obtained from :

The operating system's Security Context Management services (for calls within
the application's own address space)

-OR-

An operating system Secure IPC service (for all cross-address-space calls
within the application's machine)

-OR-

A Secure Association service or GSSAPI (for all calls across a network)

Complying with these guidelines will allow an application to use the identity
information already collected by the operating system and the network services
running on the platform, without having to prompt the user for a username and
password.


ΓòÉΓòÉΓòÉ 4.2.2. Integrated User Management Guidelines ΓòÉΓòÉΓòÉ

Applications should take advantage of the user management facilities of the
system to maintain the image of a single user database and a single user
management interface for the system. The application does not have its own user
registry service.


ΓòÉΓòÉΓòÉ 4.2.3. User Names and Passwords Guidelines ΓòÉΓòÉΓòÉ

To allow users to have a single username and password everywhere, it is
necessary to define a username and password syntax which all applications in
this environment recognize.  If all applications in this environment used the
same authentication service and took their user definitions from the same user
registry, this would be simple; the user registry would define the username and
password syntax, and the authentication service would accept that same syntax.
The actual environment is more complex, however; it must allow "old"
applications to continue to function with their existing username and password
syntax for some period of time.

To enable single logon, therefore, applications must adhere to the set of
username and password syntax rules which are designed to be acceptable to a
very wide range of existing secure applications.

1.  Each user account has a globally unique name which conforms to the DCE
    principal naming rules and has the following form:

           <accountname>   ../<leaf>
           <pathcomponent>

2.  Applications which do not use an account's globally unique name should use
    a flattened form of the globally unique name, formed by extracting the
    <leaf> component of the globally unique name and applying any "character
    folding" (e.g. mapping to all uppercase or to all lowercase) necessary to
    satisfy the application's requirements.  DCE does not require that <leaf>
    names be unique in a cell, so it is possible that a single cell might
    contain two accounts named

        /.../C=USA/O=IBM/PSP/Austin/LANSystems/sec/principal/design/Bob
        and
        /.../C=USA/O=IBM/PSP/Austin/LANSystems/sec/principal/marketing/Dept505/bob

3.  In this case, both users' flattened names would be bob (or possibly BOB).
    Care should be taken, when assigning usernames in cells which support "old"
    applications using flattened names, to avoid this kind of name collision.

     -AND-

    Each user account has a password whose syntax is constrained by the same
    rules which govern <leaf> names (these rules are described above).  Note
    that this password syntax captures the password restrictions of most UNIX
    systems.


ΓòÉΓòÉΓòÉ 4.2.4. Integrated Authorization Policy Management Guidelines ΓòÉΓòÉΓòÉ

Applications should take advantage of the authorization facilities of the
system to maintain the image of a single authorization policy semantics and a
consistent authorization information storage model for the system.

The application uses the authorization functions of the local file system or
the network services (e.g. DCE).  The application does not implement its own
access control service or interface.


ΓòÉΓòÉΓòÉ 4.2.5. Identified Operations Guidelines ΓòÉΓòÉΓòÉ

Applications should always perform operations under the identity of the subject
(user or identified program) which initiated those operations.

1.  (AIX/6000) The application always ensures that the identity associated with
    its processes and threads by the operating system security context
    management service correctly represents the user on whose behalf those
    processes and threads are doing work.

2.  (AIX/6000) The application always ensures that the identity and credentials
    associated with an IPC or network call correctly represent the user on
    whose behalf the call is made.

Note:  Note that "trusted server" applications, which may sometimes perform
       work under their own identities, and which may do work on behalf of
       different users at different times, may need to use local and network
       Security Context Management interfaces to change the active identities
       they represent from time to time in order to satisfy this requirement.


ΓòÉΓòÉΓòÉ 4.2.6. Authorized Access Guidelines ΓòÉΓòÉΓòÉ

Applications should always check to see if an operation is authorized before
performing that operation. The application always ensures (perhaps through use
of an underlying secure file system or other secure resource manager) that all
of the following are done before granting access to a resource it owns and
protects:

1.  The identity and credentials of the user requesting access are determined

2.  The identity and credentials are checked against the resource's
    authorization policy

3.  The access request is denied if it is not authorized


ΓòÉΓòÉΓòÉ 4.2.7. Audit Guidelines ΓòÉΓòÉΓòÉ

Applications should audit all security-sensitive operations and ensure that
audit records contain all security-relevant data about attempted operations.

1.  The application generates an audit record for each security-sensitive
    operation specified as auditable by the currently active audit policy.

2.  Each audit record includes at least the following information:

    a.  timestamp
    b.  operation identifier
    c.  operation class
    d.  unique user identifier
    e.  unique resource identifier
    f.  completion code indicating success or reason for failure


ΓòÉΓòÉΓòÉ 4.2.8. Message Protection Guidelines ΓòÉΓòÉΓòÉ

Applications should protect data transmitted over networks against modification
and disclosure.

1.  The application always implements message integrity protection (by adding a
    Message Authentication Code (MAC) to the message data) on all network
    calls.

2.  The application always implements message confidentiality protection (by
    encrypting the message data) on all network calls containing sensitive data
    (e.g. by using the message confidentiality features of GSSAPI or a secure
    association service).


ΓòÉΓòÉΓòÉ 4.2.9. Object Reuse Protection Guidelines ΓòÉΓòÉΓòÉ

Applications should ensure that data structures which are deallocated (returned
to the system) do not contain any sensitive data. The application clears all
bytes of each data structure it deallocates immediately prior to returning the
structure's storage to the system.


ΓòÉΓòÉΓòÉ 5. Interprocess Communication (IPC) ΓòÉΓòÉΓòÉ

Use of interprocess communication (communication services that are higher level
than the transport layer) enable developers to create applications whose parts
can be executed on one or multiple computers in these environments. Developers
should consider which of the following capabilities their application needs to
choose the best communication mechanism:

o   local or distributed network support
o   homogeneous or heterogeneous multivendor environment support
o   synchronous or asynchronous communication capability
o   transaction handling capabilities
Application developers who need lower-level communications control (for
example, sockets) should refer to the Transport section, and application
developers who need object management services should refer to the
Inter-Application Collaboration section.


ΓòÉΓòÉΓòÉ 5.1. IPC Services and Interfaces ΓòÉΓòÉΓòÉ

Interprocess communication services mainly deal with communications among
processes (or threads) in distributed environments.

Today, LAN Server provides the following services for communication between
applications on one or more machines in a LAN Server network:

Mailslots

Named Pipes

For applications that require communication services in a heterogeneous
environment, the following additional communication services are available:

Conversational

Remote procedure calls (RPC)

Messaging and queuing


ΓòÉΓòÉΓòÉ 5.1.1. Mailslots ΓòÉΓòÉΓòÉ

The Mailslot services API provides one-way interprocess communications based on
NetBIOS datagrams. A process can write to a (local or remote) Mailslot with a
class and priority attribute, using the Mailslot's network name. OS/2 and DOS
clients can use this API, as can other platforms that support LAN Server.


ΓòÉΓòÉΓòÉ 5.1.2. Named Pipes ΓòÉΓòÉΓòÉ

Named Pipes provide 2-way communications among (local or remote) processes.
After a server creates a Named Pipe it waits for clients, the clients can use
the standard file services (for example: DosOpen(), DosRead(),) on the Pipe's
network name, to access the Named Pipe. Named pipes have a client side and a
server side. The server side must be on a LAN Server running either the server
or peer service. The client side can run on either an OS/2 or DOS client. Named
pipes are also supported on other platforms that support the X/Open SMB
protocol.


ΓòÉΓòÉΓòÉ 5.1.3. Conversational ΓòÉΓòÉΓòÉ

In the conversation model, the distributed parts "converse" with one another
and are synchronized in a manner similar to the speakers in a telephone
conversation. This model is based on the program-to-program communication model
defined by SNA APPC, where one part of a distributed application or resource
manager initiates a conversation with another, and they then exchange
synchronous messages until the user's requests are satisfied, at which time the
conversation is terminated. Each part of the distributed application or
resource manager is responsible for maintaining the state of the conversation
and abiding by the rules of the conversation protocol. The conversational model
provides a synchronous service.

ISO has chosen the conversational model as the basis for the OSI Transaction
Processing protocol specification. X/Open's Common Programming Interface for
Communications (CPI-C) provides a common interface for the implementation of
the conversational model on all major platforms for access to both LU6.2/APPC
conversations and OSI dialogs.


ΓòÉΓòÉΓòÉ 5.1.4. Remote Procedure Calls (RPC) ΓòÉΓòÉΓòÉ

In the RPC model, one part requests a service from the other part, and awaits a
reply. With RPC, a client program includes a call stub that packages the
arguments of the call, sends them to the server program, and waits for a reply.
A companion server stub unpacks the arguments, invokes the called procedure,
packages the results, and sends a reply back to the client. RPC has a mechanism
for placing the definitions of service interfaces into the directory. It
includes a mechanism for operation across machines of different architectures,
which is supported by the stubs.

The Open Software Foundation (OSF) chose RPC as the fundamental communication
model for the Distributed Computing Environment. The DCE technology for RPC
supports connection-oriented and connectionless transports.

The RPC model is synchronous from the point of view of the calling program,
because it must wait until the requested procedure finishes its execution and
returns the results.


ΓòÉΓòÉΓòÉ 5.1.5. Messaging and Queuing ΓòÉΓòÉΓòÉ

The messaging and queuing model is characterized by the independent execution
of the partner programs. The partners communicate indirectly through message
queues, which are analogous to mail boxes, at the sending and receiving
locations. The communicating programs do not have to be active simultaneously.
Messaging and queueing support provides time-independent communication, with
the sender and receiver executing at their own pace.

The sending application uses the Message Queue Interface (MQI) to place a
message on a queue at the sending system. In the receiving system, the message
is placed on a queue for the receiving application. There can be a single
queue, or separate queues for different types of messages. Distributed
applications may be created by arranging the flow of messages between
serially-reusable message processing programs.


ΓòÉΓòÉΓòÉ 5.2. IPC Guidelines ΓòÉΓòÉΓòÉ

There are three major communication models in Communication Services:

Conversational

Remote Procedure Calls (RPC)

Messaging and Queuing


ΓòÉΓòÉΓòÉ 5.2.1. Conversational Guidelines ΓòÉΓòÉΓòÉ

In this fully-duplexed connection-oriented model, a series of synchronous
messages are passed and remain active in both directions during the
conversation. This model is based on the peer-to-peer communications defined by
SNA APPC. X/Open CPI-C provides a common interface for the implementation on
all major platforms. For application developers, CPI-C provides a consistent
call-based API on top of APPC (cf. APPC-verbs with control-block API). IBM
provides CPI-C language bindings for all its compilers.


ΓòÉΓòÉΓòÉ 5.2.2. Remote Procedure Calls (RPC) Guidelines ΓòÉΓòÉΓòÉ

In RPC, clients make calls on the remote server as if it were local, and
synchronously waits and gets the reply from the server as the return value or
as out-parameters (using threads, asynchronous operation is possible, but by
itself, RPC is synchronous). To the application developer, the only difference
in this call that makes it remote is the additional binding handle parameter,
which should be obtained through NSI  (Name Service Interface), using only the
service's advertised name in the DCE directory (not network address). Using the
RPC mechanism, servers become generic network resources and register themselves
to the DCE Directory (and Security) services, (or administers do that), so that
authorized clients can discover them by name, and make authenticated RPCs on
them. RPC also takes care of data format differences via data-marshalling and
"receiver makes it right" rule so application developers should not worry about
it. Special care should be taken for passing pointers as RPC parameters since
the server is running in a different address space.

IBM offers the DCE services on AIX/6000, and selected services on OS/2 and
other IBM platforms now.


ΓòÉΓòÉΓòÉ 5.2.3. Messaging and Queuing Guidelines ΓòÉΓòÉΓòÉ

Messaging and queuing allows applications to communicate with each other
asynchronously, through queue managers so that the delivery is guaranteed, and
all the routing details are encapsulated inside queue managers and transparent
to applications.  For this, application developers should use MQSeries (IBM
Messaging and Queuing Series) which is a family of products that enable
programs to talk to each other across a heterogeneous network using a simple
and consistent API (MQI) by just Getting/Putting messages in the queue: MQPUT,
MQGET are the main functions and there are also several more utility calls.
All the difficult work of communication is hidden from the application
developer. 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) function:

o   Queue name-to-address resolution
o   Message routing
o   Message Channel Agent (MCA)
o   Administration
o   Sync point
MQSeries is available on all major IBM platforms.


ΓòÉΓòÉΓòÉ 6. Inter-Application Collaboration (IAC) for Compound Documents ΓòÉΓòÉΓòÉ

To carry out complex tasks in distributed computing environments, applications
often collaborate among themselves, taking the roles of clients and servers in
turn. Compared to a single monolithic application trying to execute complex
tasks on its own, modularized applications that can act as components in
collaboration environments tend to be more flexible and customizable, easier to
maintain, and more easily reused as components in multiple environments.

In the distributed IAC environment, the unit of applications in collaboration
are system objects which can be very fine-grained (e.g. an object in memory, a
part-handler method, an executable, a DLL, a process), or very coarse-grained
(e.g. a component framework), and these system objects can be distributed
across the network. When discussing IAC, anything that can provide a service
through well-defined interfaces can be called an application. System objects
with state-data and methods are used to model these applications.

Compound Documents is an architecture where interapplication collaboration is
exploited. Compound document support requires a set of interoperability
protocols designed to produce a single document for the user. Compound
documents is an architecture in which the center of communication is a data
object usually called a document or a container object (e.g. text, spreadsheet,
multimedia object, etc. with associated applications or methods that can
manipulate this document) which can link or embed other documents. These
provide productivity improvements for the user. For example, a text container
object linking a spreadsheet and embedding a sound object can provide the
containing text with the following capabilities:

o   automatic updates, as the linked spreadsheet is modified
o   in-place edit/activation of linked or embedded objects (with the
    applications which were used to create the objects) without ending the
    current application
o   customization through scripting
o   drafting and version control


ΓòÉΓòÉΓòÉ 6.1. IAC Services and Interfaces ΓòÉΓòÉΓòÉ

For some compound document support, IBM currently provides (for OS/2) support
for Dynamic Data Exchange (DDE). DDE is broadcast-based and suitable for
smaller objects. Future releases of LAN Server will provide network support for
DDE. DSOM will be added to this environment to provide support for distributed
objects.

Application developers who need more compound document capabilities can write
to OpenDoc. Because it will use SOM/DSOM, OpenDoc will provide, transparent to
the application developer, interoperability and all the benefits of the CORBA
specification.

In the following figure, observe that OpenDoc is built on the SOM object model
to provide compound document support for applications. SOM/DSOM provides a
language neutral distributed object model and interoperability with other
object request brokers (ORBs) and other object models like the Component Object
Model (COM).

OpenDoc enables the creation of compound documents (documents which are created
and edited by several cooperating applications working within a single
document). In OpenDoc, a document is a collection of parts, each of which is
much like a present day document. Each part has a type, and this type is used
to choose a part handler. which will help the user edit, view, and print that
part of the document. No single application has complete control of the
document; therefore, protocols are required to make sure that the various
pieces stay in sync.

OpenDoc supports irregular document frames, version control, in-place editing,
stable linkage, distributed objects (via DSOM), and interoperability with OLE.
OpenDoc will be available on OS/2, AIX/6000, Windows, and Macintosh.


ΓòÉΓòÉΓòÉ 6.2. IAC Guidelines ΓòÉΓòÉΓòÉ

OpenDoc is the recommended architecture for compound document support in these
environments. The IBM OpenDoc code is available on The Developer Connection for
OS/2. OpenDoc has the following technology components:

o   OpenDoc architecture for document embedding
o   Open Scripting Architecture (OSA): this supports customization and
    automation (macro) capabilities of compound documents
o   Bento Storage format
o   CORBA-compliant, SOM-based object model

In the OpenDoc environment, there is a process called document shell which
dispatches/arbitrates the events/messages among the parts in the container
document and the part-handlers. The part-handlers are the routines/methods that
can manipulate the associated parts. IBM's OpenDoc platform offerings will
implement the storage protocol between part handlers and the document shell,
and application developers need to provide the part-handlers only (minimal
work). These part-handlers themselves can be considered modularized
applications for the collaboration.

1.  Use OpenDoc for IAC to support compound documents.

2.  Use IAC for services available from other applications rather than
    re-implementing those services.


ΓòÉΓòÉΓòÉ 7. Transport ΓòÉΓòÉΓòÉ

The term transport is used to refer to the base network service layer (OSI
reference model layers 1-4) for providing end-to-end connectivity for client
and server applications across the network. The transport single system image
goal is to enable applications to communicate without being aware of the
physical network topology. A customer should be able to select a network
protocol and/or communication hardware based on business needs such as cost and
performance. This selection should be independent of application usage.

The transport layer shields the complexity of different network types from
higher layer services and applications by the provision of a transport
independent application programming interface (API). Use of this
transport-protocol-independent API insulates the application from network
changes, and enables the application to run on different networks including
TCP/IP, NetBIOS, IPX and SNA. The transport architecture allows:

o   clients to install a single network protocol to access services from
    different networks. This optimizes workstation performance, RAM and disk
    usage, and minimizes administration overhead.

o   servers to support multiple protocols to be accessible by clients installed
    on different types of networks.


ΓòÉΓòÉΓòÉ 7.1. Sockets Framework ΓòÉΓòÉΓòÉ

Berkeley Software Distribution (BSD) 4.3/4.4 Sockets (as defined in POSIX
1003.12) is the recommended standard transport API in these environments.
Sockets using its AF_INET address family option to access TCP/IP and is
available on most operating system platforms.

Sockets on OS/2 is an IPC/Transport framework supporting multi-protocol access
including local IPC (AF_OS2), TCP/IP (AF_INET), and NetBIOS (AF_NB). The
following figure shows today's OS/2 implementation; this architecture will be
implemented on additional platforms in the future.

Using the socket API model, applications can be written in a protocol
independent manner. Via the use of the AF(address_family) option, and by
specifying protocol specific address (usually acquired from a application level
directory services such as DCE CDS), applications can choose a specific network
protocol to communicate with remote transport applications. The remote
transport application can be written to sockets, XTI or other transport
protocol specific APIs (e.g.  Sockets (AF_NB) to communicate with NetBIOS 3.0
NCB I/F).

Multiprotocol Transport Networking (MPTN)

Transport Services

Supported Platforms


ΓòÉΓòÉΓòÉ 7.1.1. Multiprotocol Transport Networking (MPTN) ΓòÉΓòÉΓòÉ

OS/2 Sockets (AF_INET) may also be used to support TCP/IP applications running
over NetBIOS and SNA network unchanged. This is provided under the socket
transport framework. In addition, applications written to current SNA APIs
(e.g. CPI-C) and NetBIOS NCB I/F can also run on nonmatching networks such as
TCP/IP, SNA and NetBIOS LAN. This mix-and-match networking capability is
described under CTS (Common Transport Semantics) within IBM's MPTN
architecture. CTS supports matching and nonmatching transport API and protocol
access. MPTN complements existing mixed protocol access standards such as RFC
1001, 1002 for NetBIOS on TCP/IP by providing an architecture framework to
enable communications applications using a protocol specific API to run on
different networks.


ΓòÉΓòÉΓòÉ 7.1.2. Transport Services ΓòÉΓòÉΓòÉ

Sockets provide two basic sets of transport services:

o   Connection-oriented data transfer:  Connection-oriented services provides
    reliable end-to-end delivery of data. It is peer-to-peer and full duplex.
    The data transfer type may be stream (SOCK_STREAM) or message
    (SOCK_SEQPACKET).

o   Connection-less (SOCK_DGRAM) data transfer:  Connection-less services
    provide unreliable message-based data transfer and include unicast,
    multicast and broadcast message support.


ΓòÉΓòÉΓòÉ 7.1.3. Supported Platforms ΓòÉΓòÉΓòÉ

Sockets is supported on most operating system platforms:

o   Sockets (AF_OS2, AF_UNIX) for local domain is available on OS/2. and
    AIX/6000.

o   Sockets (AF_INET) for TCP/IP is available for DOS, Windows(called Winsock),
    OS/2, and AIX/6000.

o   Sockets (AF_NB, AF_PX) for NetBIOS is available on OS/2.

o   Sockets (AF_INET) over NetBIOS is available on OS/2.

o   Sockets (AF_INET) over SNA is available on OS/2, AIX/6000. and MVS.

If the sockets interface is not available for a platform, other protocol
specific interfaces may be used. These include:

o   NetBIOS API on native NetBIOS protocol for DOS, Windows, OS/2, and
    AIX/6000.

o   NetBIOS API on TCP/IP for NetBIOS applications migration to TCP/IP network
    is available on DOS, Windows, OS/2, AIX/6000 and other systems.

o   NetBIOS API on SNA protocols will be available on OS/2.

o   SNA CPI-C and APPC APIs on TCP/IP is available on OS/2 and AIX/6000.


ΓòÉΓòÉΓòÉ 7.2. Transport Guidelines ΓòÉΓòÉΓòÉ

This section describes how to build a network independent application to
interoperate with remote applications for new and migrating applications
environment.

Application Use of Transport Services

Transport Interoperability


ΓòÉΓòÉΓòÉ 7.2.1. Application Use of Transport Services Guidelines ΓòÉΓòÉΓòÉ

Applications do not use transport services directly. Higher layer communication
services such as RPC are used instead.

-OR-

Applications only use transport services directly if interoperability with
existing transport level applications is required or when there is a
requirement which cannot be met by using other higher layer communication
services.


ΓòÉΓòÉΓòÉ 7.2.2. Transport Interoperability Guidelines ΓòÉΓòÉΓòÉ

1.  Use Sockets AF_INET as the transport independent interface over any network
    type. Native TCP/IP network should be used for internetworking over
    heterogeneous systems.

2.  Use Sockets as the common IPC/Transport API (non-AF_INET address families)
    to access other native protocols for interoperability with remote
    applications writing to specific transport.


ΓòÉΓòÉΓòÉ 8. System Management ΓòÉΓòÉΓòÉ

In distributed environments the need for system management has become an
important customer priority. Customer requirements include the need to be able
to manage both local and remote systems using basic system administration
skills. The effectiveness and success of the system management applications
will be only as good as the data received from the managed applications.

System Management Requirements are defined for applications to enable support
of a common set of functions. This will allow the customers to manage their
systems through a set of managing applications. Our goal is to provide a common
look and feel for system management functions across the AIX/6000 and OS/2
systems. The following requirements are considered key to a successful system
management strategy and are defined in detail in the following sections:

o   Reliability, Availability and Serviceability (RAS)

o   Software Management

    -   Packaging
    -   Delivery/Distribution
    -   Configuration
    -   Installation

o   License Management

o   Performance Monitoring

o   Remote System Management Access
when


ΓòÉΓòÉΓòÉ 8.1. Reliability, Availability and Serviceability (RAS) ΓòÉΓòÉΓòÉ

RAS is defined as Reliability, Availability and Serviceability. The Reliability
of a system is defined as the ability to recover from detected errors and to
avoid the hanging or crashing of the application or system. Availability is the
ratio of the total time a functional unit/application is capable of being used
to the total time the functional unit/application is required for use.
Applications can improve availability by having administrative functions
operate concurrently with system operation. This includes the changing of
configuration, installation of software fixes, and changing of hardware
components without disrupting (i.e. rebooting) the system operation.
Serviceability is the ability to identify and repair system failures in the
least amount of time with minimal disruption to the customer operation. The
provision of good Problem Determination/ Problem Source Identification (PD/PSI)
is a key factor in the design of a serviceable system.

To have a serviceable system the application should follow the defined strategy
and all the PD/PSI tools and aids should ship with the base application and be
installed as the installation default. These strategies and functions include:

o   Message Format/Logging

o   Failure Detection/Formatting

    -   Error Log
    -   Trace
    -   Dump

o   PD/PSI Start Points

o   Problem Determination Guide

o   Application/API Test Utilities
chart.


ΓòÉΓòÉΓòÉ 8.1.1. What is PD/PSI? ΓòÉΓòÉΓòÉ

Problem Determination (PD) is described by IBM as the process to determine if
the problem is caused by hardware or software. Once the problem is isolated to
hardware or software then the next step is to determine the Problem Source
Identification (PSI) within the software (SW) category (this would be the
software module) or the Customer Replaceable Unit (CRU) within the hardware
(HDW) category (this would be a defective hardware component such as memory or
adapter card).

With a good implementation of PD/PSI, the customer will be able to isolate and
replace a hardware or software defect without any assistance from an external
support structure. To enable this, the application developer will need to
utilize the guidelines described in this section.

This PD/PSI goal should also apply to the initial installation/configuration of
the system. The customer should be able to install and configure the system
successfully without assistance from an external support structure.


ΓòÉΓòÉΓòÉ 8.1.2. Future Considerations for RAS ΓòÉΓòÉΓòÉ

DCE

OSF is proposing a DCE logging facility that should be available in the OSF/DCE
1.1 release.

OS/2 and AIX/6000

OS/2 and AIX/6000 will have logging facilities based on the FFST technology
added in future base releases. See the reference section for additional
information on FFST.

Object-Oriented Environments

RAS requirements will not change when programs are written using an
object-oriented programming language but can be standardized by taking
advantage of inheritance (sub-classing) technology. Applications should be
designed with a basic set of RAS classes that all application classes can
inherit such as:

 o   Trace activation/deactivation
 o   Test command
 o   Return current status (active/waiting/etc)
 o   Performance monitor activation/deactivation

RAS requirements such as logging, that don't require class message support
since logging is non-solicited, can use either a procedure call or send a
message to a logging object if the services are defined as object classes.

There is no industry/platform standard set of RAS classes available today for
RAS class inheritance.


ΓòÉΓòÉΓòÉ 8.1.3. RAS Guidelines ΓòÉΓòÉΓòÉ

To be effective in the detection and isolation of problems, the application
should support the following set of RAS compliance categories to ensure that
the user/administrator will be able to isolate and resolve problems without
support center involvement.

Message Format

Message Logging

Failure Detection

PD/PSI Start Point

Problem Determination Guide (PDG)

Application/API Test Utilities


ΓòÉΓòÉΓòÉ 8.1.3.1. Message Format Guidelines ΓòÉΓòÉΓòÉ

Messages that are generated should be timestamped, have an ID, and have help
information if the original message requires more detailed text for problem
clarification. The timestamp allows the message to be associated with a message
log entry so that the proper information about the condition can be gathered.
Error messages should also be hypertext enabled for easy access to supporting
logs and related information. Information displayed while using the hypertext
links should be logged to a common file for later access by a support group. An
example would be if a message indicates that the error log contains additional
information and the error log instructs the user to run diagnostics. As the
user is proceeding through the steps (message, error log, diagnostics) the
information that is retrieved at each step should be stored in a common file
for later retrieval. See Customer Information Messages Guidelines for message
format and see Internationalization Guidelines for requirements.

Code that detects error conditions but has no user interface should make sure
that all detected errors have unique return codes. These return codes can then
be passed to the requesting interface for accurate generation of messages and
user actions. Error return codes should not be consolidated to generate a
single message such as "program error, unable to continue" when individual
messages would have more isolation capabilities.


ΓòÉΓòÉΓòÉ 8.1.3.2. Message Logging Guidelines ΓòÉΓòÉΓòÉ

In many cases it is very helpful to reproduce the events that led up to the
error condition via a message log. This log should contain the messages that
the application generated and are displayed to the user. Log access should have
supporting help panels that describe the probable cause and action required to
correct the problem.

1.  Application generated messages are timestamped and describe probable cause
    and action with supporting helps as described in Customer Information
    section.

2.  Supporting documentation exists for message definition that can be used for
    remote assistance. Message logging is provided for additional information.


ΓòÉΓòÉΓòÉ 8.1.3.3. Failure Detection Guidelines ΓòÉΓòÉΓòÉ

Error Log

Applications should be designed to detect, log (if required), and recover from
errors. Errors that are logged should have timestamps and information that can
be used to tie together all the events that are associated with the error
condition. If messages are displayed, the error log entries should use the same
wording and error causes so the administrator can associate the displayed
message with an error log entry to perform effective PD/PSI.

Sufficient error information should be logged so that probable cause of the
error can be determined and displayed when the error log is used for PD/PSI
activities. If the probable cause of an error can be different for
installation, execution, or user activities the log should indicate these
differences. An example would be that a CONFIG.SYS error in OS/2 might be the
cause of an error condition during install time but would probably not be a
cause on a system that has been working and no changes have been made to the
CONFIG.SYS file. Applications should also allow for the generation of error
notifications to remote administration systems. See Remote System Management
Access section for remote system management requirements and the reference
section for pointers to programming documentation that applies to your
development platform for logging error information.

Trace

Traces are used to gather dynamic information about system and application
activities to assist with PD/PSI and performance-related activities. The
performance trace requirements are described in Performance Monitoring section.

The PD/PSI trace should be designed to isolate the flow at major APIs in the
system such as the interface into and out of each application and be able to
trace events through the application. Most trace data associated with an
individual application is unique. A formatter should be provided to display the
trace information and registers, buffers and other areas should be clearly
labeled. Any error conditions (i.e. bad return codes, invalid commands) should
be detected and described by the formatter.

The user of an application feature should be able to activate tracing when the
feature is started. An example would be if you were trying to start TCP/IP and
a failure occurred on activation. If the TCP/IP program had been required to be
active before the trace could be started it would not have been able to capture
the initial activation error sequence. OS/2 and AIX/6000 provide trace services
that can be used to gather information from code that has been instrumented.
AIX/6000 provides a trace formatter and a mechanism for applications to use
that formatter to format their trace data. Many applications have defined their
own trace facilities.

Dump

Applications, when in an unrecoverable system error condition, should support a
dump procedure that allows a total or partial dump (by component) of the
application space or process. There should be a formatter that will describe
the cause of failure in a symptom string format that can be used by the support
structure to identify rediscoveries. This symptom string information should
also include failing module identification.

The AIX/6000 system dump is a tool for isolating system problems. Selected
areas of the system can be dumped by defining them in the master dump table via
a dmp_add kernel service and in the component dump table via the sys/dump.h
header file. Each function that is dumped can install a unique formatting
routine that can be called by the crash command for interpretation and
formatting of system structures. The crash command provides a variety of
subcommands for viewing both an active system as well as a system image file.

1.  (AIX/6000) Device drivers use the AIX/6000 RAS facilities by instrumenting
    the code with syslog calls for error logging, dmp_add for dump, and event
    hooks for trace.

2.  (DCE) Base platform (AIX/6000 and OS/2) services should be used for error
    logging, dump, and trace support.


ΓòÉΓòÉΓòÉ 8.1.3.4. Error Log, Trace and Dump Formatting Guidelines ΓòÉΓòÉΓòÉ

Failure information that is logged for future display should have a format
program for error log, dump, and trace information.

1.  Formatters are provided for the display of error log, dump, and trace
    information with probable cause of failure displayed when possible.

2.  Probable cause analysis programs are used for multiple log correlation and
    analysis.


ΓòÉΓòÉΓòÉ 8.1.3.5. PD/PSI Start Point Guidelines ΓòÉΓòÉΓòÉ

There should be a single desktop start point that will provide access to the
PD/PSI tools by the administrator and should be accessible both locally and
remotely. See Remote System Management section for remote access requirements.
There should be selections for trace, error logs, dump, and any other tools the
application provides. There should also be a hardcopy description of what to do
in case of a problem in a situation when the application is in a state that it
can no longer communicate with the operator or send information to the
operating system for recovery. This documentation should also describe the
error log, trace, dump, and message detail information.

The application PD/PSI tools have a desktop start point where all PD/PSI tools
can be accessed.


ΓòÉΓòÉΓòÉ 8.1.3.6. Problem Determination Guide Guidelines ΓòÉΓòÉΓòÉ

The PDG should describe the problem determination procedure from starting point
to finish. The PD/PSI starting information should address all detectable
situations (e.g. system inoperable, unexpected results, etc) and describe the
use of the supporting tools such as error logs, traces and dumps that can be
used for remote assistance.

The application has PD/PSI documentation to support system-inoperable
conditions, remote assistance requirements, and supporting documentation for
the interpretation of error log, dump, and trace information.


ΓòÉΓòÉΓòÉ 8.1.3.7. Application/API Test Utilities Guidelines ΓòÉΓòÉΓòÉ

During PD/PSI, an important step is to identify the parts of the system that
are working correctly. When only APIs are shipped with an application, the only
way to verify correct operation may be with a test program. This test program
plays an important role when isolating user vs application API problems. Sample
test programs should be made available for verification of client/server
end-to-end communications (e.g. Send/Receive). There is also a need to have
test commands that will verify the correct operation of system path components
(e.g. TCP/IP ping) and local hardware (e.g. wrap, loop-back modem commands).

The application has test programs, utilities and test commands that will verify
correct operation of the application APIs and program and hardware paths.


ΓòÉΓòÉΓòÉ 8.2. Software Management ΓòÉΓòÉΓòÉ

Software applications pass through a lifecycle that starts with development and
packaging, then delivery to users, then distribution within users'
organizations, then configuration and installation on on users' workstations,
then possible additional configuration after installation, then actual
operation, then possible updating and/or removal from the users' systems.
During this lifecycle the objective is to enable the user, the support
personnel, and the development organization to manage the application images
that are on the user's workstation.

This figure illustrates the applications lifecycle stages. Each box represents
a separate process in the software lifecycle from Software Product Development
in the beginning to Deinstall at the end. Note that there are no separate steps
for software maintenance or updates; software updates and fix packages flow
through the same steps as the initial software releases.  A point release or
fix package may skip a configuration step (because previous configuration still
applies),  but the path should be the same for application updates as for
original products.  Where differences between AIX/6000 and OS/2 apply, there
are notes beside the process boxes.

The requirements for the stages of software management include the following:

o   Packaging  provides the data required to manage the software during its
    lifecycle.

o   Delivery to Customer  requires that products be media independent, e.g.,
    easily copied from one media type to another.

o   Distribution within Customer Organization  provides for management of code
    servers, code packages, customer workstations, and groups of workstations.

    IBM's NetView Distribution Manager/2 (NetViewDM/2) and NetView Distribution
    Manager/6000 (NetViewDM/6000) are examples of software distribution
    applications for OS/2 and AIX/6000.

o   Feature Selection / Configuration  before installation provides for
    unattended installation across a network.

o   Installation  makes applications executable on the workstation. Feature
    selection and configuration determines what code is actually installed on
    the workstation.  Client/server applications can minimize the code and data
    that is required on each client workstation.

o   Configuration  changes can be made after installation is complete, either
    locally and remotely.

o   Operation  of the software application is now possible by the customer
    until a fix package update is applied, a later release of the application
    is installed or the application is removed from the workstation. An
    inventory of the software on each workstation is required to enable other
    applications or updates to the original application to perform prerequisite
    checking.

    Runtime licensing of software provides the customer with usage records for
    the software and insures the customer is in compliance with the software
    license agreement.

o   Deinstall  is the removal of an application without impairing the operation
    of the other software on the workstation.

o   Maintenance  of application software uses all the previously listed stages.
    Updates to an application require the same software management that the
    original application does.


ΓòÉΓòÉΓòÉ 8.2.1. Software Management Services and Interfaces ΓòÉΓòÉΓòÉ

The Current Environment

The Future Environment


ΓòÉΓòÉΓòÉ 8.2.1.1. The Current Environment ΓòÉΓòÉΓòÉ

AIX/6000 provides a software management tool called installp and documents how
to package AIX/6000 applications to use this facility in the AIX/6000 General
Programming Concepts publication. There is also a software distribution
product, NetView Distribution Manager/6000, available on AIX/6000 that can
distribute and install software to AIX/6000, OS/2, and Window systems.

For OS/2 and Windows applications IBM provides Software Installer for OS/2 and
Software Installer for Windows, respectively. IBM also publishes the CID
Enablement Guidelines that describes how to develop an OS/2, DOS, or Windows
install program that can be executed remotely on an unattended system. By
following these guidelines a software developer can produce an application that
can be distributed and installed by the OS/2 product NetViewDM/2 or by the
AIX/6000 product NetViewDM/6000.


ΓòÉΓòÉΓòÉ 8.2.1.2. The Future Environment ΓòÉΓòÉΓòÉ

POSIX draft standard, P1378.2 Draft 12, March 1994, Software Administration
describes software management utilities that will be available in the fugure
releases AIX/6000 and future releases of OS/2. When the POSIX software
administration utilities are available on AIX/6000and OS/2, applications will
be able to package software so it can be installed easily and managed
consistently on AIX/6000 and OS/2 systems. IBM's Software Installer for OS/2
product will provide migration for its application install programs to the
POSIX software administration utilities.

Future releases of OS/2 will provide a means to configure and customize the
system without having to update shared ASCII files like CONFIG.SYS and OS2.INI.
These new functions will help application install and remove software without
altering the operation of other applications.


ΓòÉΓòÉΓòÉ 8.2.2. Software Management Guidelines ΓòÉΓòÉΓòÉ

Packaging

Delivery to Customer

Distribution with Customer Organization

Feature Selection/Configuration

Installation

Configuration after Install

Deinstall

Maintenance


ΓòÉΓòÉΓòÉ 8.2.2.1. Packaging Guidelines ΓòÉΓòÉΓòÉ

1.  (AIX/6000) The application is packaged for remote installation using
    installp.

2.  (OS/2, DOS, Windows) The application meets the CID Enablement
    Specifications.

3.  (OS/2) IBM's Software Installer for OS/2 is used to install the
    application.

4.  (Windows) IBM's Software Installer for Windows is used to install the
    application.


ΓòÉΓòÉΓòÉ 8.2.2.2. Delivery to Customer Guidelines ΓòÉΓòÉΓòÉ

1.  The application is independent of delivery media and provides utilities to
    copy from one media to another, for example from CDROM to disk.

2.  Utilities are provided to update application images with fixes.

    -OR-

    Updates are made only with replacement of application images.


ΓòÉΓòÉΓòÉ 8.2.2.3. Distribution within Customer Organization Guidelines ΓòÉΓòÉΓòÉ

Within a customer's organization software applications can be distributed to
code servers and to user workstations without user participation.  IBM's
software distribution family of products NetViewDM, NetViewDM/2 and
NetViewDM/6000 provide common platforms for the distribution of data and
applications to customer workstation.

To take full advantage of these distribution applications, developers should
provide remotely installable software as described by the Installation
Guidelines or provide software that can be cloned.  To support cloning an
application must provide for configuration after installation. The application
can be distributed and installed by the IBM's NetViewDM, either as a clone or
remote installable application.


ΓòÉΓòÉΓòÉ 8.2.2.4. Feature Selection / Configuration Guidelines ΓòÉΓòÉΓòÉ

Application features should be selectable prior to install, and all
configuration options should be able to be specified before install.  This
allows the administrator at the customer site to preselect and preconfigure
software before it is installed on a remote unattended system.

1.  (AIX/6000) Feature selection of the application can be accomplished before
    installation.

2.  (OS/2, DOS, Windows) All of the configuration options of the application
    can be specified in a CID response file for remote installation.


ΓòÉΓòÉΓòÉ 8.2.2.5. Installation Guidelines ΓòÉΓòÉΓòÉ

OS/2 and DOS applications should be CID-enabled as defined by the CID
Enablement Specifications. This includes the requirement to be able to install
on unattended systems.

A CID-enabled application should:

o   Transfer application diskettes to a defined code server
o   Generation and support of response file to define configuration options
o   Command line parameter support to name files used
o   Install code from any network drive (redirected install)
o   Pass defined return codes to the software distribution manager
o   Write progress information (error/history) to logs
o   A reboot return code allows the software distribution manager (SDM) to
    reboot the system once after multiple installs.

CID install programs are best designed as two separate functions.  The first,
user interface program, generates command and response files. The second
program, the install engine, uses these files to drive the actual copies and
update files. In this manner the install and configuration user interfaces can
be separated for the actual install across time and space.  In other words, an
administrator can select and configure an application,  and then later
distribute the application to be installed later on remote unattended customer
machines.

AIX/6000 applications should be installable by installp. The AIX/6000 General
Programming Concepts publication in the reference list describes the packaging
file formats required to use installp.

1.  (AIX/6000) Application uses installp as described in the AIX/6000 General
    Programming Concepts publication.

2.  (OS/2, DOS, Windows) Application can be installed remotely by a software
    distribution manager on the users system.

3.  (OS/2, DOS, Windows) A GUI install utility is provided to create the CID
    response file for the remote unattended install.

4.  (OS/2) IBM's Software Installer for OS/2 is used to develop the application
    install program.

5.  (Windows) IBM's Software Installer for Windows is used to develop the
    application install program.


ΓòÉΓòÉΓòÉ 8.2.2.6. Configuration after Install Guidelines ΓòÉΓòÉΓòÉ

Applications should be configurable before and after installation. Requiring
the customer to find installation media just to change a configuration
parameter can be very annoying and time consuming. A local or remote
administrator or user should be able to configure the software.  Just as CID
enablement and  installp provide remote unattended install, these same
techniques should be used to provide remote unattended configuration updates.

1.  The application allows configuration options to be changed after install
    (without reinstalling).

2.  The application continues the install without the configuration options
    being completed. The user is allowed to configure the application at first
    execution.

3.  The application can be remotely configured after install.


ΓòÉΓòÉΓòÉ 8.2.2.7. Deinstall Guidelines ΓòÉΓòÉΓòÉ

An application should be able to deinstall (remove itself) and reinstall itself
on a workstation.  This includes removing directories, files, and updates the
application makes to shared file, e.g., CONFIG.SYS on DOS or OS/2.  Care should
be exercised when removing text from shared files because there is no standard
way of checking to see if other applications are dependent on the same
parameters.  If other applications depend on changes made to shared files, then
the deinstalling application should leave the changes in place.

1.  The application can deinstall itself without affecting the system or other
    applications.

2.  The application can install itself multiple times without affecting its own
    or any other application's operation.


ΓòÉΓòÉΓòÉ 8.2.2.8. Maintenance Guidelines ΓòÉΓòÉΓòÉ

The updates to an application are made with the same tools and procedures as
the original install.


ΓòÉΓòÉΓòÉ 8.3. License Management ΓòÉΓòÉΓòÉ

License management policy enforcement using electronic techniques via embedded
API calls is called technical license management or  technical licensing. The
license management guidelines assume that the application makes use of the
security mechanisms described in the security section for user authentication
and authorization. Technical licensing is the runtime enforcement of a selected
license policy using electronic keys for:

o   Software (asset) execution control (the ability to limit application
    executions to the number of applications licensed)
o   Software asset management (the ability to know how many applications are
    licensed, who is using them, and where they are being used)
o   Protection of software intellectual property rights.

Today, the software industry licenses copies of software. It is important to
know how many copies are being used at any point in time. This is called
concurrent licensing. This technical licensing capability is currently
supported for AIX/6000 using NetLS and will be in future releases of OS/2.
iFOR/LS will be the name of the next release of this technology from IBM. NetLS
and iFOR/LS technology will be interoperable. iFOR/LS will be a license manager
product which implements technical licensing technology.

Application developers and suppliers may want a method, or methods, which allow
them to control access to and the use of their applications. The control
depends entirely upon the policy chosen by each application developer. In most
cases, this is necessary to ensure that the developers receive fair
compensation for use.  The most common control method used by software
developers is licensing, where the license can be provided through technical
(software or hardware) or contractual means using a written license.  Written
licenses are always a viable option but written license agreements do not
provide the level of control provided by technical licensing (the use of
software passwords or keys). Therefore, application developers will continue to
require technical licensing methods to complement written legal contracts. It
is apparent that software and hardware resources must be managed on a
network-wide basis for maximum efficiency. However, the resulting requirement
for network-wide sharing of software licenses and/or license keys may be less
apparent.

The capabilities of iFOR/LS include:

o   License control
o   Asset management (through the use of licenses)
o   Logging (under user control)
o   Server flexibility
o   Additional sales channels through the use of "try and buy" type licenses.


ΓòÉΓòÉΓòÉ 8.3.1. Today's Environment without License Management ΓòÉΓòÉΓòÉ

The following figure illustrates a LAN without license management. These LANs
are not using any technically licensed applications. Currently there are very
few tools to assist the administrator in managing software assets. There are
eight applications being used -- two licenses have been purchased for each of
the eight applications.  As can be seen, three applications (APPL1, APPL3 and
APPL8) of the eight violate the licensing agreements because three copies of
each are being used concurrently on different workstations (for example: APPL1
is on workstations "A","B", and "C"). There is no metering application to
monitor or to limit the number of applications being used concurrently.

In the following figure, metering has been added to the same LAN by adding a
system-type application to the file server and then moving the code for the
eight applications to the file server and using it as a combination file and
code server. The term metering is used in three ways by the industry:

o   Simple counting of application requests (executions)
o   Counting application requests and accumulating the execution time
o   Counting application requests and limiting the concurrent executions to
    those applications according to the number of paper licenses purchased.

This figure illustrates license conformity using metering to count application
requests and limit the concurrent executions. The parameters for the metering
program were set to allow two copies to execute concurrently (in conformance
with the license agreement). This conformance requires that some workstations
wait for applications since this LAN is under licensed (i.e., it does not have
as many concurrent runtime licenses as it has concurrent requests).


ΓòÉΓòÉΓòÉ 8.3.2. The Licensing Environments ΓòÉΓòÉΓòÉ

The following figure illustrates the use of applications which are license
enabled.  This means that the applications contain API calls which request a
license key from a license key server before it proceeds with its execution. A
license enabled application does not have to reside on a code server in order
to have the concurrent execution requests controlled. The control resides in
the application as a policy which logically represents a paper license.

As each application initializes, it requests a license key from the license
server.  Each of the first two application requests (for APPL1 thru APPL8) is
able to get a key since each application on the LAN has been licensed for two
concurrent users. The third concurrent request for each of the applications
receives a return code which means that licenses are available but they are all
currently in use.  APPL1, APPL3 and APPL8 (in the illustration) all received
this return code and all decided to queue on the server and to wait until a
license if free.  The alternative action was to hard stop.

Each application in a license queue will periodically poll the license server
to determine if a license has been made free. As soon as a license is
available, the application will begin its execution phase.


ΓòÉΓòÉΓòÉ 8.3.3. License Policy ΓòÉΓòÉΓòÉ

A licensing policy enforces a written licensing agreement. It answers the
following types of questions:

o   What type of license keys are required (or types of licenses)?
o   What does the application do when it does not find a license key?

    -   Does it queue for a license key?
    -   Does it quit immediately?
    -   Does it continue but with a warning message?
    -   Does it continue but in a degraded mode?
o   Is more than one license key required and why?
o   What happens if the user requests exceed the count of available licenses?

iFOR/LS has the capabilities to enforce some very complex policies. Software
developers should keep the supported policy as simple as is possible yet strict
enough to protect intellectual property and assets. For AIX/6000 and OS/2,
sample policy code will be made available to those who purchase the Application
Developer's Kits (ADKs).


ΓòÉΓòÉΓòÉ 8.3.4. License Guidelines ΓòÉΓòÉΓòÉ

An application is not considered to be license-enabled unless it uses the
iFOR/LS APIs. The following guidelines assume that the application will use
iFOR/LS for future releases of OS/2 and NetLS for AIX/6000.

With software license management, the user may or may not have a printed
license to read that explains the policy supported by the enabled application.
The application developer should provide a means of explanation (e.g. a file or
online help information) so that the interested user can read the description
of the actual policy being enforced by the software.

1.  The APIs should be installed at the proper places within the code to
    request a license. The license initialization and license request APIs
    should be issued prior to or during the initialization of the application.

2.  Applications should notify the license server at intervals specified by the
    license policy that the application is still using the license.  This is
    best implemented using a timer thread which issues the API to notify the
    server. Use the netls_check_license API.

3.  When the application requests a license and learns that the workstation is
    not registered, the application should notify the user that the workstation
    is not registered and inform the user as to how to properly register the
    workstation.

4.  A mechanism (e.g. a file or help information) should be provided which
    states the license policy enforced by the software.

5.  The implemented policy should be simple and easy to explain and to
    understand.

6.  The user should be given online instructions on how to obtain a license
    when the software determines that a license does not exist.

7.  When the application is started and it does not find a license, it

8.  cannot exit without telling the user how to purchase a license.

9.  Applications should provide the flexibility to include the name, telephone
    number, and/or address of the reseller who sold the software to the end
    user. The design of this flexibility is left to the application developer.

10. The user should have the option, during runtime, to choose whether or not
    to wait for a license when one exists but is not available.


ΓòÉΓòÉΓòÉ 8.4. Performance Monitoring ΓòÉΓòÉΓòÉ

Performance Monitoring tools should provide a single view of the networked
system and the capability to monitor each individual node. A Managing System
provides access to, and collection of, the data from the various nodes (Managed
Systems). A Managing System is defined as a computer or workstation where the
results of the performance monitoring are viewed or observed. A Managed System
is the computer or workstation where the performance-instrumented application
is executing and performance data is being collected and sent to the Managing
System. Following is an example of a performance monitoring environment.

Application developers should instrument their code with user metrics to
support the various performance monitoring activities that take place
throughout the application's life cycle. Examples of user metrics are:

o   number of transactions or executions per second
o   number of bytes sent or received from a remote server
o   response times for server requests
o   number of logged-on users
o   number of data buffers currently allocated

Following is an example of performance monitoring instrumentation.

This performance monitoring instrumentation can be used during the application
design and development phases to support design validation analysis,
verification of the application versus its performance objectives, memory leak
analysis, and determining the causes of performance problems that are detected
during development and testing.

Once the instrumented application is operational, it can be monitored for
performance characteristics. This data can be used to support system
administration and management activities which include tracking system resource
utilization, identifying growth trends and additional resources that will be
needed, and identifying symptoms of operational performance problems.

Performance monitoring is used to address performance problems/questions from
customers. Application support personnel may use performance monitoring
instrumentation from either the design and development phase (for problem
symptoms) or the system administration and management phase (for identifying
problem causes).


ΓòÉΓòÉΓòÉ 8.4.1. Supported Platforms ΓòÉΓòÉΓòÉ

In the following discussions of the supported platforms and their performance
monitoring instrumentation and tools, only the discussions under the System
Administration and Management topics are to be considered as implementation
guidelines within the scope of this document. The instrumentation and tools
discussed under the Application Design and Development topics are included as
general, useful information on optimizing the performance of the application,
but not as implementation guidelines.

OS/2

AIX/6000


ΓòÉΓòÉΓòÉ 8.4.1.1. OS/2 ΓòÉΓòÉΓòÉ

Instrumentation for System Administration and Management

Application programmers should use the SPM/2 API to instrument their code with
user metrics for system administration and management.

To support OS/2 application and device driver user metric enabling, the SPM/2
API allows you to:

o   Register/deregister counter groups for collection
o   Set/clear semaphore to control access to counter groups
o   Increment/decrement counter value
o   Start/stop timer
o   Set queue (counter/timer pair) value
o   Add/remove a specified number of elements to/from a queue
o   Query current time.
The instrumentation resulting from this API enables performance monitoring by
using the SPM/2 and/or LAN NetView Monitor products. The description on how to
instrument user code, and to define and register user metrics for both of these
products is provided in the SPM/2 documentation (see References).

Described briefly, user performance metrics for an instrumented application can
be collected by SPM/2 and made available for real-time processing by using the
SPM/2 API to:

o   Determine active SPM/2 components
o   Retrieve real-time and historical data
o   Initialize/terminate a monitor session
o   Open/close a monitor session file
o   Read an instance of sample data from a monitor session file
o   Query the status of active and inactive monitor sessions.

Instrumentation for Application Design and Development

For support of the application design and development phases, there is no
performance trace facility provided for OS/2, and thus, no trace
instrumentation methodology. The rich features of SPM/2 and LAN Netview Monitor
are helpful in this environment.

Using the SPM/2 API, application developers can register performance counters
and timers for 16-bit and 32-bit OS/2 applications, device drivers, file system
device drivers and virtual device drivers. These instrumented performance
counters and timers can be used in the ANSI C programming language development
environment to optimize application or device driver performance.

The SPM/2 Theseus capability supports memory usage analysis and memory leak
detection. See Performance Monitoring References, "Memory Debugging for C and
C++ Programs" for guidelines, tools, and techniques.


ΓòÉΓòÉΓòÉ 8.4.1.2. AIX/6000 ΓòÉΓòÉΓòÉ

Instrumentation for System Administration and Management

To instrument application code under AIX/6000 for performance system
administration and management, application developers should define and
register user metrics using the AIX/6000 System Performance Measurement
Interface (SPMI) API. The data thus collected can be reported using the
AIX/6000 'xmperf' tool. How to use these facilities is described in the
AIX/6000 documentation.

Instrumentation for Application Design and Development

For support of the application design and development phases, application
developers should instrument their code for the AIX/6000 Trace Facility. The
documentation on how to do this is provided in the AIX/6000 Performance Tuning
Guide. Instrumentation should be included to mark entry and exit for each API
that is developed for application users, and to trace the processing flow in
key application functions and algorithms. (Consideration should be given to
including this instrumentation in the shipped application; however, it may be
decided to insert these calls conditionally and compile them out when the
application is shipped).

Trace can be postprocessed by the trcrpt tool, producing a very detailed,
integrated view of the application's activity within the context of the rest of
the system. See AIX/6000 Trace documentation for more information.

Additionally, AIX/6000 provides a number of other tools which should be used to
optimize application performance during design and development. A partial list
of these tools for AIX Version 4.1 includes (many of these are available for
earlier versions of AIX):

o   tprof:

    tprof allows developers to profile their applications.  That is, the
    application can be executed, and tprof will identify portions of the
    application in which most of the CPU time is being spent. In cases where
    portions of an application are not available in source form (perhaps
    involving a joint development activity, or integration with some
    third-party application/subsystem), tprof is still capable of providing
    subroutine level profiling of the entire application.  In the more likely
    case where source is available, tprof can provide profiling down to the
    source statement level.

o   stem:

    stem is a unique tool for tracing program flow. It allows programmers to
    insert arbitrary instrumentation code into the entry and exit of any
    executable. This instrumentation code can write its data into a shared
    memory segment, or directly to a file.  Stem is shipped with a base set of
    instrumentation routines that allow a user to immediately produce a
    detailed call-graph of any executable. Like tprof, stem does not require
    source code.  Unlike tprof, stem can trace every call, both in the user's
    code, and in any library that code uses (even if no source code for that
    library is available). Tprof is based on a sampling technique, so it might
    miss certain short-duration activity.  Stem will catch every call.

o   svmon:

    svmon allows for process and system-wide memory usage to be profiled. It
    provides a snapshot of the current state of memory for a process or for the
    entire system.  It also provides detailed segment usage.

o   rmss:

    rmss allows a developer to experiment with an application's sensitivity to
    real memory size.  By simultaneously varying a machine's real memory size
    and repeatedly executing an application, a profile of memory size versus
    paging activity is obtained.  Note that rmss actually simulates a change in
    the machine's real memory allocation.

o   fdpr:

    fdpr applies a technique called feedback directed program restructuring
    (fdpr) to effectively speedup an application execution. fdpr reorders
    elements of an executable to improve that executable's use of system cache.
    fdpr would be applied as the last step to program development, after all
    programmer-initiated and compiler-directed optimizations had been applied.

o   bigfoot:

    bigfoot provides in depth trace of a program's memory footprint. Every page
    reference (with the exception of pinned pages) is captured into an event
    log. The result is a very detailed profile of an application's memory
    activity. This profile is available at the process and subroutine level,
    with both tabular and graphical outputs.


ΓòÉΓòÉΓòÉ 8.4.2. Performance Monitoring Guidelines ΓòÉΓòÉΓòÉ

Application developers should use the facilities provided by this environment
to instrument a broad range of user metrics, and to register and report these
metrics as part of the larger set of performance metrics maintained for this
environment.

1.  The application provides comprehensive instrumentation of user metrics
    which support evaluation by a system administrator of resource usage by
    this application in a system context.

2.  The application registers these metrics with the provided system
    performance measurement facility, and provides report capabilities as
    required by that facility. AIX/6000 applications use the SPMI API to
    register these metrics. OS/2 applications use the SMP/2 API.


ΓòÉΓòÉΓòÉ 8.5. Remote System Management Access ΓòÉΓòÉΓòÉ

Remote system management provides the administrator with a Single System Image
of the network of systems that is being managed.  Network resources, such as
gateways, routers, and servers show up in this image and can be monitored and
controlled by the administrator. Managed systems will have a Simple Network
Management Protocol (SNMP) agent that forwards status to and accepts commands
from a managing workstation. Subagents can be included with the application to
make their resources manageable. Subagents instrument enterprise-specific
application MIBs to these management applications. A Management Information
Base (MIB) is required for each subagent to define its management attributes.
For example, a mail server could be enabled for remote management by including
a MIB definition and an SNMP subagent that would allow the systems
administrator at the remote console to:

o   see that the mail server is operating normally
o   observe the performance of the mail server in real time or from a recorded
    log
o   access RAS facilities (trace, error log, dump)
o   start or stop the functions of the mail server.

The job of the remote system manager, e.g, NetView/6000 (NV/6000) or LAN
NetView (LNV), is to process error messages and/or alarms generated by managed
systems. The RAS section of this document provides information describing how
each application should generate errors, messages and alarms/alerts. The remote
system manager can record these error messages and produce trouble tickets to
track repair of failed systems and components.


ΓòÉΓòÉΓòÉ 8.5.1. Current Remote Systems Management ΓòÉΓòÉΓòÉ

LAN NetView and NetView/6000 provide remote management of network as well as
system resources (OS/2, AIX/6000 and other systems) through the use of SNMP.
Operating system and machine resources are being instrumented using the host
resource MIB (RFC-1514 of Internet Engineering Task Force). Applications can
also be managed by LAN NetView on OS/2 and NetView/6000 on AIX/6000 by writing
subagents to these management applications.

The following figure illustrates the current remote system management
environment. Either LAN NetView on OS/2 or NetView/6000 on AIX/6000 can be the
management console (the managing system) for the network and for the
applications running on the managed systems in the network.  Applications that
run on OS/2, AIX/6000, Windows, DOS, or any system that provides a TCP/IP
protocol stack and an SNMP agent can be managed by these applications. For
example, Novell NetWare servers provide an SNMP agent to enable remote systems
management.

AIX/6000 provides the SNMP Multiplexing Protocol (SMUX) to allow an application
to create subagent to the systems 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.


ΓòÉΓòÉΓòÉ 8.5.2. Future Remote Systems Management ΓòÉΓòÉΓòÉ

o   Communications protocols supported 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's (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 the CORBA compliant Object Request Broker,
    e.g, IBM's DSOM.  This will allow applications to enable objects for
    management and will provide a consistent object view of the network and all
    the systems and resources.

o   IBM has proposed an event management system to the Open Software Foundation
    (OSF) to be included in a future version of the Distributed Computing
    Environment. This event management system will provide event notification
    and routing to management applications. Documentation will be available in
    a future OSF RFC.

o   A future version of the IBM DCE Developers Toolkit will contain a SOM class
    library for DCE administration objects. Application developers can use this
    library to generate administration applications with user interfaces that
    are consistent with other DCE management applications.


ΓòÉΓòÉΓòÉ 8.5.3. Remote System Management Guidelines ΓòÉΓòÉΓòÉ

This section provides the guidelines for developers to make their applications
manageable from remote systems.

1.  (AIX/6000) The application provides a MIB definition and an SNMP subagent
    written to the SMUX interface.  Functions are provided to see if the
    application is running properly and to allow the application to be stopped
    and started.

2.  (OS/2) The application provides a MIB definition and an SNMP subagent
    written to the DPI.  Functions are provided to see if the application is
    running properly and to allow the application to be stopped and started.

3.  Additional data is provided to allow the performance of the application to
    be monitored.


ΓòÉΓòÉΓòÉ 9. Extended Operating System ΓòÉΓòÉΓòÉ

Naming

Printing


ΓòÉΓòÉΓòÉ 9.1. Naming ΓòÉΓòÉΓòÉ

Single System Image for naming means that there is a single consistent view of
the namespace for all users.  Parts of the namespace may reside on physically
different systems, but to the user the namespace appears as if it is local.
This is called location transparency.

The namespace is used to store the names of all the resources in the network as
well as those resources' attributes.  Network resources may be logical devices
such as queues and physical devices such as printers and servers.  All network
resources are called objects.  Examples of objects commonly found in a network
are users, organizations, printers, and printer queues.

An attribute is a piece of information associated with an object.  An object's
attributes may define its class, network address, or other values.  So, for
example, if a resource moves from one server to another server, its attribute
for network address will change, but the object's resource name remains
unchanged.  Attributes are also used to search for objects.

Policies for placement of objects in the namespace and the composition of names
of objects provide a additional means to portray a single system image of the
namespace.  Policies also provide a consistent way of accessing objects in the
namespace as a step toward application portability.

The naming service provides a set of services and protocols accessed via a set
of interfaces.  These interfaces and services assist the programmer in
developing applications.  The interfaces and services can be categorized as:

o   base context operations: operations on names, such as binding a name to a
    reference, looking up the reference bound to a name, and unbinding a name.

o   attribute operations: operations on attributes such as get, create, delete,
    modify, and search.  Operations may be for a single attribute or multiple
    attributes.

The following example demonstrates a use of the name service. The following
figure represents a part of a namespace hierarchy that contains printer objects
and their attributes. Objects 'A', 'B', 'C', and 'D' are printers with their
associated attributes in brackets. The following terms are associated with this
example:

o   Object type: printer
o   Service: search
o   API: X/Open Directory Service API ds_search()
o   Service Provider: name service offered by the naming system, e.g. cell
    directory service or X.500

An application composes the following request based on user input and invokes
the ds_search API and receives the result.

Request list all of the postscript printers in bldg901

Result returns a list of printer objects that have the attributes postscript
and building 901 (i.e. printer objects 'A' and 'B' are returned)


ΓòÉΓòÉΓòÉ 9.1.1. Naming Interfaces and Services ΓòÉΓòÉΓòÉ

This section addresses the current naming environment and where the technology
is going in the future for the application developer.


ΓòÉΓòÉΓòÉ 9.1.1.1. The Current Environment ΓòÉΓòÉΓòÉ

Naming interfaces and services today are provided in this environment by LAN
Server and the Distributed Computing Environment (DCE).

Location transparency and single system image are achieved in LAN Server by use
of a namespace that includes, among other things, aliases, user definitions,
and application definitions. Aliases describe attributes and the location of a
shared file, print, or serial device resource. User definitions store
information about users including password, group memberships, logon
assignments, and other attributes. Application definitions define a set of
attributes such as command line parameters and location for a shared
application. The structure of the namespace and the types of objects that can
be represented in the namespace are fixed, and applications do not explicitly
reference the namespace. Instead, the application developer uses the Net* APIs
to define servers and resources. Through the use of these APIs, the servers and
resources being defined are automatically inserted correctly into the LAN
Server namespace, i.e., the User Account Subsystem (UAS) and the Domain Control
DataBase (DCDB).

DCE introduces international standards for naming interfaces and services. The
Name Service Interface (NSI) provides interfaces for name lookup, binding, and
unbinding for the DCE Cell Directory Service (CDS). The X/Open Directory
Service interface (XDS) provides interfaces for reading, adding, deleting, and
modifying directory entries, attribute manipulation such as comparison and
search, enumeration of directory entries and its subordinates.  The XDS
interface is available for use with the CDS and the X.500 directory service.
(Note:  XDS and X.500 currently are supported only on AIX, and the XDS search
API is not supported for the Cell Directory Service). These interfaces (NSI and
XDS) are X/Open standards and part X/Open's Distributed Computing Service
profile. The following figure illustrates the current naming API environment.

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 comprise that cell,
o   a security namespace to hold user, group, account, and policy, information,
    and
o   a file namespace to hold file data.

DCE provides for the joining of these namespaces in a hierarchy by a convention
called junctions.  This joining is also known as federation. This federation
provides logically a single namespace with a single global root denoted by
'/...'.

Refer to OSF DCE Administration Guide: Planning, Configuring, and Starting Up
DCE, Appendix A: The DCE Cell Namespace, for complete layout and description of
the DCE namespace.


ΓòÉΓòÉΓòÉ 9.1.1.2. The Future Environment ΓòÉΓòÉΓòÉ

Naming interfaces and services will extend the current environment to one in
which interfaces and services are generalized international standards. The
following figure illustrates the goal for the naming environment. The naming
interfaces are expected to appear in two forms:  an object interface and a
procedural interface. The object interface is that defined by the Object
Management Group (OMG) Joint Object System Services (JOSS) Naming
specification. OMG++ refers to the current OMG naming interfaces enhanced to
provide attribute operations.  These enhancements do not yet exist, but for OMG
to become the naming interface of choice for object-oriented programming these
extensions are necessary.  The procedural interface is that defined by X/Open's
Federating Naming (XFN) specification. The XFN specification also defines a
wire protocol for this interface.

Noticeably missing from this environment are the NSI and XDS interfaces.
Support for backward compatibility for these interfaces will remain because:

o   NSI provides a small, simple interface for lookup and bind for applications
    that use only that level of service
o   XDS is still the standard API for the X.500 and X.400 environment
o   NSI and XDS are standards now and there are applications written to those
    interfaces.

The following figure illustrates a future with this backward compatibility.

Namespaces are expected to be federated in a standardized manner. An object may
be looked up through a standard interface where the name (path) to access that
object may span multiple namespaces. Policies are expected to be provided to
govern the hierarchical relationships among the logical namespaces. Mappings
for existing APIs are expected in this environment so that existing
applications can continue to work. The following figure illustrates the
building blocks for federation.


ΓòÉΓòÉΓòÉ 9.1.2. Naming Guidelines ΓòÉΓòÉΓòÉ

DCE Cell Directory Service (CDS) Usage Guidelines, available as DCE RFC 44.0
from OSF, contains useful coding and testing hints for application developers.
Many of the DCE guidelines listed below are from that document.

Naming APIs

User Names and Passwords

Location Transparency

Namespace Usage


ΓòÉΓòÉΓòÉ 9.1.2.1. Naming APIs Guidelines ΓòÉΓòÉΓòÉ

Applications should use those APIs available in the environment.

1.  (LAN Server) The application uses the LAN Server Net* APIs to access the
    naming service.

2.  (DCE) The application uses X/Open DCE APIs, NSI and XDS, to access the
    naming service.


ΓòÉΓòÉΓòÉ 9.1.2.2. User Names and Passwords Guidelines ΓòÉΓòÉΓòÉ

To allow users to have a single username and password everywhere, it is
necessary to define a username and password syntax which all applications in
this environment recognize.  If all applications in this environment used the
same authentication service and took their user definitions from the same user
registry, this would be simple; the user registry would define the username and
password syntax, and the authentication service would accept that same syntax.
The actual environment is more complex, however; it must allow "old"
applications to continue to function with their existing username and password
syntax for some period of time.

To enable single logon, therefore, applications should adhere to the set of
username and password guidelines (refer to security guidelines) which are
designed to be acceptable to a very wide range of existing secure applications.

1.  Each user account has a globally unique name which conforms to the DCE
    principal naming rules.

2.  Applications which do not use an account's globally unique name should use
    a flattened form of the globally unique name.

3.  Each user account has a password whose syntax is constrained by the same
    rules which govern the <leaf> part of user names.


ΓòÉΓòÉΓòÉ 9.1.2.3. Location Transparency Guidelines ΓòÉΓòÉΓòÉ

The service or subsystem should be able to have its physical location moved
transparent to the application locating it.

1.  (LAN Server) The application uses the LAN Server Net* APIs to access the
    naming service. The application does not use UNC (Universal Naming
    Convention) names.

2.  (DCE) Register servers in a host-independent group or profile. This group
    or profile would be used by clients to locate the server. This provides
    location transparency since clients would otherwise have to specify the
    unique server entry.


ΓòÉΓòÉΓòÉ 9.1.2.4. General Namespace Guidelines ΓòÉΓòÉΓòÉ

1.  (LAN Server) The application uses the LAN Server Net* APIs. This implicitly
    provides the correct namespace (UAS and DCDB) usage.

2.  (DCE)

    a.  Store server (resource) binding information in the CDS namespace along
        with attributes needed for that object or service to allow for that
        object/service to be located. While the CDS namespace can be used to
        store arbitrary information, it is not intended as a general purpose
        database. Use of the CDS namespace for purposes other than the storage
        of server bindings might impact the performance of the DCE cell.
    b.  Organize the namespace by creating a well-organized directory
        structure. Create directory namespace entries as you would files and
        directories in a filesystem.  A well-organized namespace makes
        searching and management easier.
    c.  Subsystems register their services under the <cellroot>/subsys
        directory.  The DCE directory below subsys is for DCE core services.
        Resource managers should create a directory directly beneath subsys
        using a descriptive name.  For example, LAN Server would register its
        services under the <cellroot>/subsys/ibmls directory. The
        <cellroot>/hosts/hostname directory contains bindings for DCE services
        that are running on that hostname.
    d.  Keep the root of the namespace clean for ease in searching.  A few
        well-known entries in the root are acceptable.
    e.  Choose sensible names for entries such as the name of the server or a
        name that relates better to what the server does than its own name. For
        working in a heterogeneous international environment, refer to
        Internationalization Guidelines.  Do not use dynamically generated
        UUIDs (Universal Unique Identifiers) as CDS entry names.  Names are
        meant to be meaningful.
    f.  Groups should be used to store a set of identical server entries.
        Profiles should be used for other collections of logically related
        entries.
    g.  Use RPC Name Service (NS) group to store bindings for a set of
        identical servers for server redundancy. A client can perform a lookup
        in the group and continue searching until it finds a server that is up
        and able to satisfy its request.
    h.  Use profiles instead of groups to register a collection of server
        entries with different interfaces.  This makes searching more
        efficient.
    i.  Register server entries in the most specific profile or group that
        makes sense.  This avoids unnecessary searching in higher-level
        profiles and groups.
    j.  Clients should use /.../cell-profile as a default profile if no
        host-independent group or profile name was specified.


ΓòÉΓòÉΓòÉ 9.2. Printing ΓòÉΓòÉΓòÉ

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 programming
interfaces that hide the complexity of the printing environment. The result is
a Single System Image (illustrated below) which:

o   hides the physical location of the print objects accessed through the print
    APIs

o   hides the specific print service providers that are processing the APIs and
    implementing the print objects

o   hides 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 on
which an application runs. Print objects typically supported include "job",
"queue" and "printer" where a job is a printable entity with options such as
number of copies, a queue is a repository for jobs that are scheduled for one
or more printers supported by the queue, and a printer is a physical device on
which a job is printed.

In the future, the print APIs and the corresponding print objects supported
will be standardized across OS/2 and AIX/6000 to enable true application
portability across a multi-system environment.


ΓòÉΓòÉΓòÉ 9.2.1. Print Interfaces and Services ΓòÉΓòÉΓòÉ

There are two main aspects of the print APIs.

o   An application submits a print job consisting of the print options and data
    that is printable by the target printer object (e.g. Postscript). The data
    can be printed on the target printer or can be translated by the print
    service that processes the data on behalf of the target printer object.

o   An application enables a user or administrator to create, delete, modify
    and manage print objects.


ΓòÉΓòÉΓòÉ 9.2.1.1. Job Submission ΓòÉΓòÉΓòÉ

First, the application selects a queue for the job. The application can use the
default queue defined for the operating system or present a list of queues to
the user and use the queue they select.

Once the application selects a queue, the application obtains the job
properties for the queue to be used by the print service to print the job. Job
properties, also known as job attributes, might include print quality and page
orientation. Typically, the job properties come from the printer driver that
will be used to print the job.

The application chooses application-specific options, such as a range of pages
to print. The application also selects print service options such as number of
copies and job priority.

The queue, job properties, application print options and print service options
are collectively called job setup options. Once the job setup options have been
established, the application then submits the print job to the print service.
The print job consists of the job setup options and a printable document.


ΓòÉΓòÉΓòÉ 9.2.1.2. Print Object Management ΓòÉΓòÉΓòÉ

Most applications do not need to directly manage print objects such as jobs,
queues and printers. Instead, the print service providers deliver user
interface applications that enable users and systems administrators to manage
these objects.

For applications that manage print objects, these interfaces enable
applications to create, delete, configure, modify and control the print objects
supported by the service providers.


ΓòÉΓòÉΓòÉ 9.2.1.3. The Current Environment ΓòÉΓòÉΓòÉ

Today, application developers use current operating system printing APIs based
on the operating systems on which their applications run. On OS/2, the Single
System Image is provided by the procedural print framework in OS/2. 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-attached or remotely-attached printers. Furthermore, PM and OS/2
applications can control and manage print objects through a single set of 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.


ΓòÉΓòÉΓòÉ 9.2.1.4. The Future Environment ΓòÉΓòÉΓòÉ

In the future, IBM's Distributed Print Management Framework, based on Palladium
Version 2, delivers the Single System Image across multiple operating systems
including OS/2 and AIX/6000. Users, system administrators and application
developers can use a single set of interfaces for advanced user and systems
management functionality regardless of the physical location of the printer and
print resources being used and managed.


ΓòÉΓòÉΓòÉ 9.2.2. Printing Guidelines ΓòÉΓòÉΓòÉ

Typically applications allow users to print documents with document formats
supported by the application. For applications that print documents, the
guidelines include:

Queue selection
Job properties selection
Print service options
Application print options
Job submission

For applications that manage print objects, the guidelines include:

Job object management
Queue object management
Device object management
Additional print object management


ΓòÉΓòÉΓòÉ 9.2.2.1. Queue Selection Guidelines ΓòÉΓòÉΓòÉ

1.  The application uses the default queue to submit a print job.

    a.  PM and OS/2 2.1 and above applications should use the SplEnumQueue API
        and search the returned list of queues for a queue with an fsType field
        value of PRQ3_TYPE_APPDEFAULT to obtain the default queue.
    b.  PM and OS/2 2.0 applications should use the PrfQueryProfileString API
        with an application name of PM_SPOOLER and a key name of QUEUE to
        obtain the default queue.
    c.  AIX/6000 applications should not determine the default queue since
        AIX/6000 determines the default queue with the qprt CLI.

2.  The application enables the user to select a queue from a list of available
    queues.

    a.  PM and OS/2 applications use the SplEnumQueue API to obtain the list of
        queues and then use application-specific mechanisms to present the list
        to the user and to attain their selection.
    b.  AIX/6000 applications use the lsallq CLI to obtain the list of queues
        and then use application-specific mechanisms to present the list to the
        user and to attain their selection.


ΓòÉΓòÉΓòÉ 9.2.2.2. Job Properties Selection Guidelines ΓòÉΓòÉΓòÉ

1.  The application uses the job properties of the queue selected for a print
    job.

    a.  PM and OS/2 applications should use the SplQueryQueue API to obtain the
        job properties of the queue selected for a print job.
    b.  AIX/6000 applications should not determine the job properties since
        AIX/6000 determines the job properties for the queue with the qprt CLI.

2.  The application presents to the user the job properties of the queue
    selected for a print job.

    a.  Presentation Manager (PM) and OS/2 applications should use the
        DevPostDeviceModes API to display the job properties of the queue for
        the print job. The application subsequently uses the job properties
        returned from this API to submit a print job.
    b.  AIX/6000 applications use application-specific mechanisms to present
        job properties to the user. The application subsequently uses the job
        properties to submit a print job.


ΓòÉΓòÉΓòÉ 9.2.2.3. Print Service Options Guidelines ΓòÉΓòÉΓòÉ

1.  The application presents number of copies with a default value of one. The
    user can specify a value within a valid range of values defined by the
    operating system. Applications use application-specific mechanisms to
    present this option to the user.

2.  The application presents job priority with the default value of the
    operating system. The user can specify a value within a valid range of
    values defined by the operating system. Applications use
    application-specific mechanisms to present this option to the user.


ΓòÉΓòÉΓòÉ 9.2.2.4. Application Print Options Guidelines ΓòÉΓòÉΓòÉ

1.  The application presents application-specific options to the user through
    an application's print user interface. The specific options vary by
    application but typically include a range of pages to print. The
    application presents number of copies with the application-specific
    options. The user can submit a print job from the application's print user
    interface.

2.  The application presents job properties and job priority through the
    application's print user interface.


ΓòÉΓòÉΓòÉ 9.2.2.5. Job Submission Guidelines ΓòÉΓòÉΓòÉ

1.  The application submits a print job to the default queue with job setup
    options.

    a.  PM applications should use the Dev* APIs. PM applications should
        specify the default queue, the job properties for the queue and
        PM_Q_STD for DevOpenDC.
    b.  OS/2 applications should use the SplQm* APIs. OS/2 applications should
        specify the default queue, the job properties and PM_Q_RAW for
        SplQmOpen.
    c.  AIX/6000 applications should use the qprt CLI with no queue name.
    d.  DOS applications should use the DOS APIs.

2.  The application submits a print job to the queue selected by the user with
    job setup options.

    a.  PM applications should use the Dev* APIs. PM applications should
        specify the queue selected by the user, the job properties for the
        queue and PM_Q_STD for DevOpenDC.
    b.  OS/2 applications should use the SplQm* APIs. OS/2 applications should
        specify the queue selected by the user, the job properties and PM_Q_RAW
        for SplQmOpen.
    c.  AIX/6000 applications should use the qprt CLI with the queue selected
        by the user.


ΓòÉΓòÉΓòÉ 9.2.2.6. Job Object Management Guidelines ΓòÉΓòÉΓòÉ

Most applications do not need to directly manage this object. Therefore, this
compliance category is not always applicable. However, if an application
manages this object, the following guidelines apply.

1.  PM and OS/2 applications should use the Spl*Job APIs.

2.  DOS applications should use the DosPrintJob* APIs.

3.  AIX/6000 applications should use the qcan, qchk and qpri CLIs.


ΓòÉΓòÉΓòÉ 9.2.2.7. Queue Object Management Guidelines ΓòÉΓòÉΓòÉ

Most applications do not need to directly manage this object. Therefore, this
compliance category is not always applicable. However, if an application
manages this object, the following guidelines apply.

1.  PM and OS/2 applications should use the Spl*Queue APIs.

2.  DOS applications should use the DosPrintQ* APIs.

3.  AIX/6000 applications should use the qchk, qstatus, qadm, lsallq, mkque,
    chque and rmque CLIs.


ΓòÉΓòÉΓòÉ 9.2.2.8. Device Object Management Guidelines ΓòÉΓòÉΓòÉ

Most applications do not need to directly manage this object. Therefore, this
compliance category is not always applicable. However, if an application
manages this object, the following guidelines apply.

1.  PM and OS/2 applications should use the Spl*Device APIs.

2.  DOS applications should use the DosPrintDest* APIs.

3.  AIX/6000 applications should use the lsallqdev, rmquedev, mkquedev,
    lsquedev, chquedev, chvirprt, lsvirprt, rmvirprt and lsattr CLIs.


ΓòÉΓòÉΓòÉ 9.2.2.9. Additional Print Object Management Guidelines ΓòÉΓòÉΓòÉ

Most applications do not need to directly manage this object. Therefore, this
compliance category is not always applicable. However, if an application
manages this object, the following guidelines apply.

1.  PM and OS/2 applications should use the Spl*Driver, Spl*Port and
    SplQueueProcessor APIs to manage printer drivers, port drivers and queue
    processors respectively.

2.  AIX/6000 applications should use the splp CLI to manage printer drivers.


ΓòÉΓòÉΓòÉ 10. Development Tool Delivery ΓòÉΓòÉΓòÉ

The IBM LAN Systems API Roadmap documents an application development
environment with industry-standard APIs for application portability and object
frameworks to assist developers with code reuse.  This document is delivered on
the The Developer Connection for LAN Systems.

The Developer Connection is a yearly subscription service which consists of a
quarterly CD-ROM and newsletter, and access to a private CompuServe or Internet
forum.  The Developer Connection benefits developers by providing easy access
to the most timely and in-depth development tools and information available.
The service offers: browser and catalog functions, development tools,
productivity tools, documentation, sample code, product pre-release and beta
code, promotional material and demos (IBM and 3rd party).

The Developer Connection program is becoming a recognized delivery vehicle for
development tools and toolkits from IBM in the PC arena.

o   "This is the disk to get if you're an OS/2 developer."  PC Magazine 9/94
o   Named one of the "Top 100 CD ROMs" by PC Magazine.
o   Over 10,000 subscribers for The Developer Connection for OS/2

Within the Developer Connection family the following Product Owners exist:

o   The Developer Connection for OS/2
o   The Developer Connection for Device Drivers
o   The Developer Connection for LAN Systems - this CD-ROM provides
    cross-platform support (OS/2, Windows, AIX, etc.) focussing on
    client/server development.  It is shipped for free with the Developer
    Connection for OS/2.
o   The Developer Connection for AIX

Product owners have responsibility for product content, audience satisfaction,
newsletter articles and API roadmap content.


ΓòÉΓòÉΓòÉ 10.1. Development Tool Delivery Guidelines ΓòÉΓòÉΓòÉ

The guidelines described below must be followed by Content providers (those who
develop and supply programming tools or utilities to a Developer Connection
Product owner) to enable a product or tool to be included on a Developer
Connection CD-ROM.

Required data           RAM and DASD requirements and the minimum recommended
                        configuration.
API roadmap             Overall API strategy for product and a high-level
                        description of each API/framework/object with future
                        directions as appropriate.
Icon                    A unique, well-designed and meaningful icon.
Installation requirements Standard, CD-ROM and network-enabled installation
                        mechanism
Standard format for documentation Documentation and books provided in standard
                        format(s) such as INF, BookManager, PostScript or HTML.
Execution requirements  Executes directly from CD, when feasible.
Standards               ISO 9660 compliant.
Maximum resource utilization Less then 16M.
Demo software           Time-outs (disabling traps) should be set for release
                        date + 90 days and any limitations of the demo or trial
                        software must be clearly documented.
WWWeb links             Initially, these will be maintained in-house by the
                        Developer Connection team.
Customer feedback       Need to respond to customer feedback via e-mail and
                        WWWeb and the support structure for the product needs
                        to be clearly identified.
Product classification  Need to assign appropriate classification of alpha,
                        beta, demo, pre-release, GA and provide necessary
                        content, support and legal sign-off.
Terms and conditions    Product fits the terms and conditions stated in The
                        Developer Connection license agreement.
Single point of contact Provide a single contact point for technical support
                        related to Developer Connection publishing issues.
Sample code             Must exist to demonstrate how to take advantage of the
                        programming model and the benefits it provides.
3rd-party products      Vendor must provide Vendor Evaluation Request/License,
                        IBM Mfg/Distribution Agreement and Vendor Certificate
                        of Originality.


ΓòÉΓòÉΓòÉ 11. Customer Information ΓòÉΓòÉΓòÉ

As used in this document, customer information includes all information
delivered with the application.  Each independent set of information is
referred to as an information unit. Information units include the following:

o   Help information (explanations of function panels for an application or a
    major component)
o   Message information (displayed by the application when unexpected or error
    conditions occur)
o   Softcopy information (structured like printed books, but provided in form
    to be viewed from the system or electronic media)
o   Integrated online information (viewable task-level descriptions linked to
    help information)
o   Printed information (traditional books)
o   Tutorial information (various media and interactive)

An application's information units collectively and individually represent an
interface to the user.

Information design, based on task analysis of the application, identifies the
best combination of information units to meet user requirements.  Multi-media
presentation may be selected for some information units; however, the
guidelines provided here are for visual presentation of information and do not
at this time address the full multi-media scope.


ΓòÉΓòÉΓòÉ 11.1. Customer Information Guidelines ΓòÉΓòÉΓòÉ

The following guidelines address:

o   Design and content of customer information
o   Selection of tools to produce information units

Consistent Design

Translation Enabled

Viewable or Printed Choice

CDROM Enabled

Consistent Style

Help Information

Messages

Examples

Consistent Name References

Text Tools

Graphics Tools

View Tools

Build Tools

Print Format Tools


ΓòÉΓòÉΓòÉ 11.1.1. Consistent Design Guidelines ΓòÉΓòÉΓòÉ

Applications to be used in multiple operating system environments require an
information design that provides a consistent look and feel for comparable
information from one operating system environment to another.  Otherwise, users
in a mixed environment are faced with added complexity that can lead to
misinterpretation and decreased satisfaction with the product.

1.  Comparable information is provided across all operating systems.

2.  Views are similar across all operating systems.

3.  Comparable information is provided across all operating systems.

4.  Views are consistent across all operating systems (common view tool
    supported on all operating systems).


ΓòÉΓòÉΓòÉ 11.1.2. Translation Enabled Guidelines ΓòÉΓòÉΓòÉ

If an application will be marketed in geographic areas with native languages
other than the initial development language, the application should be enabled
for translation.  If translated, customer information should comply with the
following guidelines to support translation tools designed to reuse language
segments (i.e., a phrase used multiple times throughout a book is translated
only once).  A language segment could be a name, book reference, sentence,
tabular information, note, or paragraph - any string of text can be a language
segment. For additional requirements, refer to Internationalization section.
The key to translatability is to ensure that the text is as precise, clear, and
correct as possible, taking into consideration the following:

o   Terminology (define technical terms and use terminology consistently)
o   Cultural factors (avoid country-specific examples, graphics, and numeric
    conventions)
o   Translation efficiency (clearly indicate common information and provide
    revision tags for changed source)

1.  Revision tags or comments are inserted around a complete language segment
    (not in the middle)

2.  Highlighting is the same for identical language segments


ΓòÉΓòÉΓòÉ 11.1.3. Viewable or Printed Choice Guidelines ΓòÉΓòÉΓòÉ

People vary in their preferences for printed information vs. viewable
information. Preferences are influenced by the nature of the task at hand,
situational factors, and personal styles and habits. Information access
possibilities include the traditional use of printed books (varying from
studying entire sections to quick retrieval of specific reference data) plus
several modes of viewing information on the system, such as browsing softcopy
books or retrieving specific topic descriptions.  Ideally, each user could
individually access information in the mode best suited to the task and
situation at hand. It is important to accommodate multiple access modes to
ensure usability.

1.  The application includes online help information.

2.  Information required for installation (not part of the user interface) is
    printed or provided as a file that can be printed prior to installation of
    the application.

3.  Information units provided with the application are primarily integrated
    online information; softcopy books and printed books can be ordered
    separately.

4.  Integrated online information includes topic print capability.


ΓòÉΓòÉΓòÉ 11.1.4. CDROM Enabled Guidelines ΓòÉΓòÉΓòÉ

CDROM popularity is increasing, and it has become the most practical media for
distributing applications and information. Enabling an application and its
information units for CDROM delivery facilitates inclusion with other software
in total-solution offerings (suites, collection kits, etc.). Guidelines related
to enabling applications for distribution are contained in the guidelines for
packaging and delivery in the Software Management Guidelines.

1.  Any installation routines required to access information units are enabled
    for CDROM.

2.  All information units are integrated online, softcopy, or printable files.


ΓòÉΓòÉΓòÉ 11.1.5. Consistent Style Guidelines ΓòÉΓòÉΓòÉ

Style, as used here, includes:

o   Mechanical style (e.g., grammar, punctuation, word usage, spelling, and the
    representation of numbers)
o   Content style (e.g., inclusion of glossary and index)
o   Format style (e.g., page layout, fonts, and headings)

All information units associated with an application should have a consistent
style. Adopting a style comparable to that of other applications and operating
systems likely to be used by the same customers can enhance the effectiveness
of the customer's total collection of information units.

1.  Grammar, punctuation, word usage, spelling, and the representation of
    numbers meet accepted usage standards.

2.  Information includes appropriate retrieval mechanisms, including contents
    and index.

3.  Information conforms to The Chicago Manual of Style.

4.  Information contains additional retrieval aids (e.g., glossaries, online
    search capability, and hypertext links within online information.)

5.  Graphics augment textual descriptions.

6.  Printed information is formatted for 7x9 page size.


ΓòÉΓòÉΓòÉ 11.1.6. Help Information Guidelines ΓòÉΓòÉΓòÉ

Help information should be provided for all function panels, providing
explanations of relevant tasks, options, and likely scenarios. Help information
should relate to user tasks and options, not to how the application functions.

1.  Help information is provided for all function panels.

2.  Help information provides more guidance than given on the function panel.

3.  Help information facilitates task completion for all likely user scenarios.

4.  Help information facilitates task completion for novice as well as expert
    users.


ΓòÉΓòÉΓòÉ 11.1.7. Messages Guidelines ΓòÉΓòÉΓòÉ

As used in this section, messages refers to information displayed by the
application when unexpected or error conditions occur. The format of messages
should be consistent and easy to interpret. Messages should be linked to
message explanations that address the circumstances that caused the message to
appear. If a message can result from a variety of circumstances or scenarios,
the associated explanation should address all possibilities.

1.  Message text includes a timestamp. (See Time Guidelines.)

2.  Message text includes an identifier of intended use (An example convention
    for such identifiers is where the first character is I, A, or W to indicate
    information, action, or warning, respectively).

3.  Messages are linked to explanations that indicate probable cause(s) and
    recommended user action(s).

4.  For unrecoverable messages, message text includes a complete explanation
    (linking to an explanation panel is not required).

5.  Message explanations are accessible for reference independent of actual
    message occurrence.


ΓòÉΓòÉΓòÉ 11.1.8. Examples Guidelines ΓòÉΓòÉΓòÉ

Online, softcopy, and printed information units should contain examples for
illustration of input formats, clarification of concepts, and demonstration of
task scenarios.

1.  Include generic examples of input formats

2.  Include appropriate geographic qualifiers (e.g. identify 04/15/2001 as a
    date specified in U.S. English format.)

3.  Provide examples to clarify concepts

4.  Provide extended examples to demonstrate task scenarios


ΓòÉΓòÉΓòÉ 11.1.9. Consistent Name References Guidelines ΓòÉΓòÉΓòÉ

References in customer information units to specific names (e.g., application
components) should match exactly the names as represented by the user interface
and, where applicable, the external product packaging (e.g., CDROM and diskette
labels.) Compliance is required to improve the chance of successful completion
of user tasks.

Name references are identical in all uses:

o   Information units
o   User interface
o   Packaging (including media labels)


ΓòÉΓòÉΓòÉ 11.1.10. Text Tools Guidelines ΓòÉΓòÉΓòÉ

The tool selected for creating (authoring or editing) text determines whether
document source can be interchanged with other developers. This can be
advantageous for combining information from multiple sources. A tool should be
selected that provides good document interchange support.

1.  The text tool is an industry-accepted desktop publishing tool or IBM
    BookMaster.

2.  The text tool is capable of producing online files compatible with intended
    operating system environment(s).

3.  Text is created with an SGML editor; valid SGML editors include:

    o   SoftQuad Author/Editor (runs in Windows, AIX/6000, and Macintosh
        development environments, also runs in OS/2's DOS/WIN)
    o   ArborText (runs in Sun development environment)


ΓòÉΓòÉΓòÉ 11.1.11. Graphics Tools Guidelines ΓòÉΓòÉΓòÉ

The graphic tool should be selected to optimize document interchange
capability.

1.  Graphics are created with any tool compatible with the text tool.

2.  Graphics are created with CorelDraw or a tool that produces files that can
    be imported by CorelDraw.


ΓòÉΓòÉΓòÉ 11.1.12. View Tools Guidelines ΓòÉΓòÉΓòÉ

Operating Systems vary in supported methods for viewing online and softcopy
information. The tools selected for viewing and building online and softcopy
information determine the level of similarity a user experiences across
multiple operating systems.

1.  The view tool for messages, help information, and integrated online
    information is one of the following:

    o   (OS/2) IPF
    o   (AIX/6000) IPF/X
    o   (Windows) IPF/Win

2.  The view tool for softcopy books is BookManager Read.


ΓòÉΓòÉΓòÉ 11.1.13. Build Tools Guidelines ΓòÉΓòÉΓòÉ

The tool selection for building online or softcopy information is based on the
tool for viewing that information.

1.  Files for message information, help information, and integrated online
    information are produced with one of the following:

    o   (OS/2) IPF
    o   (AIX/6000) IPF/X
    o   (Windows) IPF/Win

2.  Softcopy book files are produced with BookManager Build.


ΓòÉΓòÉΓòÉ 11.1.14. Print Format Tools Guidelines ΓòÉΓòÉΓòÉ

The following chart identifies options for producing the master files for a
printer (publisher).  Format tools control the layout of a printed page,
including placement of headings and integration of text and graphics.

1.  Information can be formatted for industry-standard 7x9-inch page size.

2.  The formatting tool produces output acceptable to the print vendor
    (publisher).

3.  Information can be formatted for industry-standard 7x9-inch page size.

4.  The formatting tool produces PostScript output with embedded graphics and
    encapsulated fonts.


ΓòÉΓòÉΓòÉ 12. Usability ΓòÉΓòÉΓòÉ

Application development organizations should hold as a primary goal providing
applications that are usable, both individually and as part of a networked or
distributed system.

Excellent usability is defined as easy, safe, intuitive use of products by
users.  It is achieved by developing user interfaces following the three basic
tenets of usability engineering:

o   Original designs based on known principles of human factors and perceptual
    and cognitive psychology,

o   Early and continual user focus, and

o   Usability assessments, as part of an iterative design-test-redesign-retest
    development cycle.

In this document, usability information and guidelines are provided for
application installation, configuration, and user interface.


ΓòÉΓòÉΓòÉ 12.1. Usability Guidelines ΓòÉΓòÉΓòÉ

It is difficult to identify absolutes in usability; one design or feature can
be usable in one system context and not in another.  Thus, much of what defines
usability is the process followed in its pursuit. Such process points may make
this section seem more vague than the others in this document.  The following
guidelines, if followed, will lead to improved usability of your application.
For complete confidence in your application's usability, a complete program of
user-centered design, including early and frequent involvement of the users,
iterative design, and usability evaluations, should be followed.

Installation and Configuration

User Interfaces


ΓòÉΓòÉΓòÉ 12.1.1. Installation and Configuration Guidelines ΓòÉΓòÉΓòÉ

1.  Allow applications to be installed on any drive chosen by the user, and
    installed from any drive chosen by the user.

    Do not force installation on the C (or any) drive, and do not place files
    on the C drive when the user has selected another drive.  It is more usable
    to allow the user to select any drive.

2.  Allow for easy back out from installing code (including application code,
    patch code, and version updates).

3.  Offer a minimal, guided install and configuration, to facilitate
    installation for the first-time, novice user.


ΓòÉΓòÉΓòÉ 12.1.2. User Interfaces Guidelines ΓòÉΓòÉΓòÉ

1.  Employ user-centered, participatory design.

     Do not depend on your own intuitions when it comes to determining the
    usability of our applications.  Engage the user in the design by gathering
    customer requirements, soliciting customer feedback on early designs, and
    incorporating users as part of the design team throughout the design cycle.

2.  Employ a consistent look-and-feel among all user interfaces.

    A consistent look-and-feel, or system personality, will lead to positive
    transfer of learning; having learned to use one application, the user will
    have a head start on knowing how to use the next one.

    a.  Understand what other applications within your environment look like.
        Be consistent with that.

    b.  Understand how the companion applications (applications that work with
        yours, or are prerequisites of yours), look and be consistent with that
        look.

3.  Select a set of user interface guidelines (for example, use CUA for OS/2
    applications), and design your interface accordingly.

    Deviate, in the name of increased usability, based only on consistent
    documented customer feedback.

4.  Employ intuitive, informational icons.

5.  Do not ask the user to provide information that is already accessible to
    the computer system.

    It frustrates the users when they must provide information to the computer
    more than once. Don't ask your users to:

    a.  Provide information they don't have.

    b.  Go and find the available disk storage.

    c.  Look up what is in system configuration files.

    d.  Know which statements within system files come before each other.  Make
        the software put the lines into the system files, and make the software
        check to insure the lines are placed in the proper order.

    e.  Make mathematical calculations when your program can ask for values and
        calculate them programmatically.

    f.  Start up any product as a prerequisite or for parameter information, do
        it programmatically.

Make the program do the work, not the customer.

6.  Maximize the ease and accessibility of frequently-done user tasks.

7.  Provide flexibility and efficiency of use.

    Accelerators -- unseen by the novice user, perhaps -- may often speed up
    the interaction for the expert user to such an extent that the system can
    cater to both inexperienced and experienced users.

8.  Provide tailorability within the user interface, to allow the users to
    customize the interface to suit their own needs.

9.  Afford command line and API access to all functions.

10. Make system status visible.

    The system should always keep users informed about what is going on,
    through appropriate feedback within reasonable time.

11. There should be a match between the system and the real world.

    The system should speak the users' language, with words, phrases, and
    concepts familiar to the user, rather than system-oriented terms. Follow
    real-world conventions, making information appear in a natural and logical
    order.  (See section on Internationalization for discussion on cultural
    differences and their reflection in user interfaces.)

12. Provide a minimalist design; provide all and only the information necessary
    for the user to complete a task, at the time when the user needs it.

    Dialogues should not contain information that is irrelevant or rarely
    needed. Every extra unit of information in a dialogue competes with the
    relevant units of information and diminishes their relative visibility.
    Extraneous information leads to unnecessary clutter on the screen, taking
    up screen real estate and requiring extra work of the user to discern the
    important information available.

    For example, if seconds are not meaningful, (if, say, the product is only
    accurate to the nearest minute), don't have the user input the seconds.

13. Require recognition rather than recall.

    Make objects, actions, and options visible.  The user should not have to
    remember information from one part of the dialogue to another. Instructions
    for use of the system should be visible or easily retrievable whenever
    appropriate.

14. Employ color sparingly, meaningfully, and usably.

    a.  Use color to code information.

    b.  Use some other variable (e.g., brightness) to code information, to
        accommodate color-deficient users.

    c.  Recognize that some color combinations are better than others.

        o   Don't use saturated blues or for text or other thin lines.

        o   Be consistent with cultural norms (e.g., red for stop or danger, in
            the U.S. and elsewhere).

15. Make no changes to the user's computing environment without asking for
    permission/confirmation.

    For example, leave all windows exactly where the user left them.

16. Allow no destructive actions (e.g., file deletion) without user
    confirmation (unless the user has optionally turned off the confirmation
    dialogs).

17. Stay informed of the IBM product line, and related applications.

    The applications are establishing the mental models of our users, and so to
    better understand our users we must know what programs they are familiar
    with.

18. The system should afford the user control and freedom.

    Users often choose system functions by mistake and will need a clearly
    marked "emergency exit" to leave the unwanted state without having to go
    through an extended dialog. Support undo capabilities, particularly during
    long processes like installation. People make mistakes.  Expect them.


ΓòÉΓòÉΓòÉ 13. References ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.1. How to Get Reference Material ΓòÉΓòÉΓòÉ

The following list gives the information necessary to obtain the reference
material.

1.  IBM Publications and Technical Reports

    Order IBM publications and technical reports through your IBM
    representative or the IBM branch office serving your locality.

2.  IEEE: POSIX Publications

    IEEE publications can be ordered by calling 1-800-678-IEEE (or
    908-981-1393).

3.  OMG (Object Management Group) Publications

    To order documents from the Object Management Group, Inc. call (508)
    820-4300, fax to [phone] or send a request to:

           Object Management Group, Inc. Headquarters
           492 Old Connecticut Path
           Framingham, MA  01701

4.  OSF (Open Software Foundation) Publications

    These publications are obtained at a bookstore.

5.  RFCs - DCE Documents

    DCE RFCs may be obtained through ftp and email. DCE RFC's may be available
    through ftp before they are available through email. For more information,
    see DCE RFC 0 (rfc0.0.txt).

    To access the DCE RFC directory using FTP, use the following commands and
    identity information:

           ftp grabbag.osf.org  (130.105.100.2)
           user:dce-rfc
           password:dce-rfc
           cd dce-rfc
           (then issue get commands for files)

    To get DCE RFCs using email, send an email message to:

           [e-mail]

    The message should have a null (empty) subject line.  The body of the
    message should consist of two lines in the following format:

           path <your-return-email-address>
           send rfc rfc<M>.<m>."roff|txt|ps"

    The following message body is an example of how to get an ascii version of
    RFC 0.0:

           path [e-mail]
           send rfc rfc0.0.txt

6.  RFCs - IETF (InterNet) Documents

    To access the DCE RFC directory using FTP, use the following commands and
    identity information:

           ftp nic.ddn.mil
           Name (address):anonymous
           Password:guest
           pathname RFC:RFCnnnn.TXT
            (nnnn refers to the number of the RFC)

    A list of all RFCs may be obtained by copying the file RFC:RFC-INDEX.TXT.

    The NIC also provides a mail service for those that cannot use FTP. Address
    the request to [e-mail] and indicate the desired filename in the
    subject field. For example,

           Subject: SEND RFC:RFCnnnn.TXT

7.  U.S. DoD Publications

    To order documents from the INFOSEC Awareness Division call [phone]
    or send a request to:

           DIRECTOR
           National Security Agency
           Attn: S33, INFOSEC Awareness Division
           Ft. George G. Meade, MD 20755-6000

    To order documents from the Government Printing Office (GPO), call (202)
    783-3238 on weekdays from  0800 - 1630 or send a request to:

           Superintendent of Documents
           U.S. Government Printing Office
           Washington, DC  20402

8.  X/Open Company Ltd., U.K. Publications

    A full catalogue of X/Open publications, together with an order form may be
    obtained by contacting your nearest X/Open office, (see list below) or
    directly from:

           X/Open Company Limited (Publications)
           PO Box 109,
           Penn, High Wycombe,
           Bucks HP10 8NP,
           England
           Tel:  [phone]
           Fax:  [phone]

    Additional information relating to X/Open publications is also available by
    electronic mail.  Please send your request to:

           [e-mail]
           [e-mail]

    There are 2 X/Open offices in the USA, one in England, and one in Japan:

              X/Open Company Ltd.              X/Open Company Ltd.
              1010 El Camino Real              3141 Fairview Park Drive
              Suite 380                        Suite 670
              Menlo Park, CA 94025             Falls Church, VA 22042-4501
              United States                    United States
              Tel:  [phone]          Tel:  [phone]
              Fax:  [phone]          Fax:  [phone]
              X/Open Company Ltd.              X/Open Company Ltd.
              Apex Plaza, Forbury Road         Kurufuru-Kanda Bldg, 9F
              Reading                          1-2-1, Kanda Suda-cho
              Berks     RG1 1AX                Chiyoda-Ku, Tokyo 101
              United Kingdom                   Japan
              Tel:  [phone]             Tel:  [phone]
              Fax:  [phone]             Fax:  [phone]


ΓòÉΓòÉΓòÉ 13.2. Introduction References ΓòÉΓòÉΓòÉ

1.  Open Blueprint Technical Overview, IBM publication order number GC23-3808.

    Provides a technical overview of the IBM Open Blueprint. The Open Blueprint
    is a structure for a distributed systems environment and provides the base
    upon which to build, execute, and manage distributed applications.


ΓòÉΓòÉΓòÉ 13.3. Base Operating System References ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.3.1. Application Portability References ΓòÉΓòÉΓòÉ

1.  POSIX 1003.1, Portable Operating System Interface (POSIX) - Part 1: System
    Application Program Interface (API) C Language, available from the
    Institute of Electrical and Electronics Engineers (IEEE). Also known as
    International Standard ISO/IEC 9945-1, ISBN 1-55937-061-0.

    An overview of system services and interfaces, and detailed syntactic and
    semantic descriptions of the API calls.  This document is independent of
    operating system.

2.  POSIX 1003.4a, Portable Operating System Interface (POSIX - Part 1: System
    Application Program Interface (API) - Amendment 2: Threads Extension C
    Language, Draft 4, available from the Institute of Electrical and
    Electronics Engineers (IEEE).

    An overview of threads services and interfaces, and detailed syntactic and
    semantic descriptions of the API calls.  This document is independent of
    operating system.

3.  X/Open Single UNIX Specification (Spec 1170) - Four Volume Set , available
    from X/Open Company Ltd., X/Open Document Number T403. The set is four
    documents published solely in electronic form:

    o   System Interfaces and Headers, Issue 4 Version 2. Spec 1170 V1 , X/Open
        Document Number S418.
    o   Commands and Utilities, Issue 4 Version 2. Spec 1170 V2 , X/Open
        Document Number S419.
    o   System Interface Definitions, Issue 4 Version 2. Spec 1170 V3 , X/Open
        Document Number S420.
    o   International Terminal Interfaces (XCURSES), I4. Spec 1170 V4 , X/Open
        Document Number S422.

Detailed syntactic and semantic descriptions for operating system services and
interfaces that are in common use across applications and operating systems.

4.  X/Open CAE Specification: System Interfaces and Headers, Issue 4, available
    from X/Open Company Ltd., X/Open Document Number C202.

    XPG/4 APIs and header files.

5.  (OS/2, Windows) See the programming reference and users guide for the
    compiler the application developer chooses.

    Detailed syntactic and semantic descriptions of C-library APIs.

6.  AIX Calls and Subroutines Reference for IBM RISC System/6000, IBM
    publication order number SC23-2198.

    Detailed syntactic and semantics descriptions for AIX/6000 operating system
    services and interfaces.

7.  Experiences with SOMobjects: Distributed System Object Model (DSOM), IBM
    publication order number GG24-4165.

    Provides examples and descriptions of DSOM.

8.  SOMobjects Developer Toolkit Publications, IBM publication order number
    S96F-8649.

    Provides programming information for SOM. Contains the following
    publications:

    o   SOMobjects Developer Toolkit Users Guide.

        An introductory guide to the System Object Model and its accompanying
        frameworks.
    o   SOMobjects Developer Toolkit Programmers Reference Manual.

        Reference material for the classes, methods, functions, and macros
        provided by the System Object Model and its accompanying frameworks.
    o   SOMobjects Developer Toolkit Collection Classes Reference Manual.

        Reference material for the classes and methods of the Collection
        Classes provided with the System Object Model.
    o   SOMobjects Developer Toolkit Emitter Framework Guide and Reference.

        Information about collection of SOM classes that allows programmers to
        write their own emitters.
    o   SOMobjects Developer Toolkit Installation/Configuration Guide.

        Instructions for installation and configuration of the SOMobjects
        Developer Toolkit.


ΓòÉΓòÉΓòÉ 13.3.2. Time References ΓòÉΓòÉΓòÉ

1.  POSIX 1003.1, Portable Operating System Interface (POSIX) - Part 1: System
    Application Program Interface (API) C Language, available from the
    Institute of Electrical and Electronics Engineers (IEEE). Also known as
    International Standard ISO/IEC 9945-1, ISBN 1-55937-061-0.

    Describes the POSIX time interfaces and services.

2.  DCE Application Developer's Guide, Open Software Foundation, version 1.0.3,
    available from the Open Software Foundation.

    Provides an overview of the DCE time services and interfaces and a detailed
    description of the programming model for DCE applications.

3.  X/Open DCE: Time Services Preliminary Specification, January 1994,
    available from X/Open Company Ltd., X/Open Document Number P313, ISBN
    1-85912-148-8.

    An overview of the DCE time services and interfaces, and detailed syntactic
    and semantic descriptions of the DCE time API calls.

4.  Year 2000 Clean, Feb. 1993, by M.D. Frawley, IBM Technical Report order
    number 93A 02208, location CPD-Raleigh.

    This document describes the pitfalls and solutions to dealing correctly
    with dates past the end of the twentieth century.

5.  X/Open Single UNIX Specification (Spec 1170) - Four Volume Set , available
    from X/Open Company Ltd., X/Open Document Number T403. The set is four
    documents published solely in electronic form:

    o   System Interfaces and Headers, Issue 4 Version 2. Spec 1170 V1 , X/Open
        Document Number S418.
    o   Commands and Utilities, Issue 4 Version 2. Spec 1170 V2 , X/Open
        Document Number S419.
    o   System Interface Definitions, Issue 4 Version 2. Spec 1170 V3 , X/Open
        Document Number S420.
    o   International Terminal Interfaces (XCURSES), I4. Spec 1170 V4 , X/Open
        Document Number S422.

Detailed syntactic and semantic descriptions for operating system services and
interfaces that are in common use across applications and operating systems.

6.  X/Open CAE Specification: System Interfaces and Headers, Issue 4, available
    from X/Open Company Ltd., X/Open Document Number C202.

    XPG/4 APIs for time and header files.

7.  AIX Calls and Subroutines Reference for IBM RISC System/6000, IBM
    publication order number SC23-2198.

    Detailed syntactic and semantics descriptions for AIX operating system
    services and interfaces for time.

8.  OS/2 LAN Server 3.0 Application Programmer's Reference, IBM publication
    order number S96F-8440.

    Detailed syntactic and semantics descriptions for OS/2 LAN Server services
    and interfaces for time.

9.  (OS/2, Windows) See the programming reference and users guide for the
    compiler the application developer chooses.

    Detailed syntactic and semantic descriptions of C-library APIs for time.


ΓòÉΓòÉΓòÉ 13.3.3. Internationalization References ΓòÉΓòÉΓòÉ

1.  System Interfaces and Headers, Issue 4, X/Open CAE Specification, Document
    Number C202, ISBN 1-872630-47-2.

    Specification of XPG/4 APIs and header files, including I18N for code-set
    independence, culture-sensitive information, messaging, and code-set
    conversion.

2.  X/Open CAE Specification: Commands and Utilities, Issue 4, X/Open Document
    Number C203.

    Specification of XPG/4 commands and utilities, including I18N gencat  to
    generate a message catalog and localedef to generate a locale.

3.  XPG4 Internationalization for OS/2, The Developer Connection for OS/2, IBM
    publication order number P06H-1971.

    Application programmer's guide to using the XPG/4 I18N APIs for OS/2
    applications.

4.  Universal Character Set Coexistence Migration (covers Unicode), X/Open
    Technical Study, Document Number E401, ISBN 1-872630-78-2.

    Describes major issues facing the implementers of X/Open-compliant and
    POSIX-compliant systems with regard to ISO/IEC 10646 support. It explains
    the implications of adopting any UCS strategy and possible applications for
    ISO/IEC 10646 and Unicode.


ΓòÉΓòÉΓòÉ 13.4. Security References ΓòÉΓòÉΓòÉ

1.  IBM Security Architecture: A model for securing information systems, IBM
    publication order number SC28-8135-0.

    Describes IBM's overall approach to building secure distributed system.

2.  Department of Defense Trusted Computer System Evaluation Criteria, DoD
    5200.28-STD.  Available from US DoD.

    Describes the evaluation criteria against which the US Government measures
    computer system security.

3.  DCE Application Developer's Guide, Open Software Foundation, version 1.0.3,
    available from the Open Software Foundation.

    Provides an overview of the DCE security services and interfaces and a
    detailed description of the programming model for secure DCE applications.
    The chapters relevant to security are 1, 2, and 39-46.

4.  DCE Application Developer's Reference,  Open Software Foundation, version
    1.0.3, available from the Open Software Foundation.

    Provides detailed syntactic and semantic descriptions of all of the DCE
    security API calls.

5.  Generic Security Service API, by John Linn (OpenVision), available as
    Internet RFC 1508 from IETF.

    Describes the structure and interface of the GSSAPI.

6.  GSS-API Extensions for DCE, by John Wray (DEC), available as DCE RFC 5.2
    from OSF.

    Describes extensions to the GSSAPI to support DCE security.

7.  GSS-API Security Service API (GSS-API) Base , available from X/Open Company
    Ltd., X/Open Document Number P308, ISBN 1-85912-253-3.

    Defines an application programming interface that provides security
    services to callers in a generic fashion. It is supportable by a range of
    underlying mechanisms and technologies, allowing source-level portability
    of applications to different environments. This document is based on RFC
    1508 and RFC 1509, which specify the Internet standards track protocol. In
    addition, it identifies probable future changes.

8.  A Generic Interface for Extended Registry Attributes, by Joe Pato (HP),
    available as DCE RFC 6.0 from OSF.

    Describes proposed extensions to the DCE Cell Registry Service architecture
    and interface which make it easier to support integration of non-UNIX
    operating system registries into the DCE cell registry architecture.

9.  DCE ACL Library -- Functional Specification, by Dick Mackey and Rich Salz
    (OSF), available as RFC 46.0 from OSF.

    Describes the OSF/DCE 1.1 ACL API and library.

10. DCE Server Auditable-Event Identification and a Proposed Audit Logging API,
    available from OSF as RFC 28.1.

    Describes the DCE Security Auditing Service and API.

11. Extended Services for OS/2 Guide to User Profile Management, IBM
    publication order number S04G-1112.

    Describes the LAN Server interfaces for logging on, and for managing users
    and resource access control lists.  Additional information concerning use
    of UPM interfaces in a LAN Server environment can be found in the LAN
    Server Application Programmer's Reference.


ΓòÉΓòÉΓòÉ 13.5. Communication Services Above Transport Layer References ΓòÉΓòÉΓòÉ

1.  Open Blueprint Technical Overview, IBM publication order number GC23-3808.

    Provides a technical overview of the IBM Open Blueprint. The Open Blueprint
    is a structure for a distributed systems environment and provides the base
    upon which to build, execute, and manage distributed applications.

2.  DCE Application Developer's Guide, Open Software Foundation, version 1.0.3,
    available from the Open Software Foundation.

    Includes an overview of the DCE RPC services and interfaces and a detailed
    description of the programming model for DCE applications.

3.  X/Open DCE: Remote Procedure Call Preliminary Specification, January 1994,
    available from X/Open Document Number P312, ISBN 1-872630-95-2.

    An overview of the DCE remote procedure call services and interfaces, and
    detailed syntactic and semantic descriptions of the DCE remote procedure
    call API calls.

4.  An Introduction to Messaging and Queuing, IBM publication order number
    GC33-0805.

    Describes the IBM MQSeries.

5.  X/Open CPI-C, March 1992, available from X/Open Company Ltd., X/Open
    Document Number C210.

    Describes the Common Programming Interface for Communication interface
    specification for accessing the SNA APPC protocol.

6.  AIX Version 3.2 Communication Programming Concepts, IBM publication order
    number SC23-2206.

    Provides overview and other technical references for sockets.


ΓòÉΓòÉΓòÉ 13.6. Inter-Application Collaboration for Compound Documents References ΓòÉΓòÉΓòÉ

1.  OpenDoc vs. OLE 2.0, by Scott Handy, is available on The Developer
    Connection for OS/2.

    Compares OpenDoc/DSOM with OLE 2.0/COM.

2.  Experiences with SOMobjects: Distributed System Object Model (DSOM), IBM
    publication order number GG24-4165.

    Provides examples and descriptions of DSOM.

3.  SOMobjects Developer Toolkit Publications, IBM publication order number
    S96F-8649.

    Provides programming information for SOM. Contains the following
    publications:

    o   SOMobjects Developer Toolkit Users Guide.

        An introductory guide to the System Object Model and its accompanying
        frameworks.
    o   SOMobjects Developer Toolkit Programmers Reference Manual.

        Reference material for the classes, methods, functions, and macros
        provided by the System Object Model and its accompanying frameworks.
    o   SOMobjects Developer Toolkit Collection Classes Reference Manual.

        Reference material for the classes and methods of the Collection
        Classes provided with the System Object Model.
    o   SOMobjects Developer Toolkit Emitter Framework Guide and Reference.

        Information about collection of SOM classes that allows programmers to
        write their own emitters.
    o   SOMobjects Developer Toolkit Installation/Configuration Guide,

        Instructions for installation and configuration of the SOMobjects
        Developer Toolkit.


ΓòÉΓòÉΓòÉ 13.7. Transport References ΓòÉΓòÉΓòÉ

1.  X/Open Single UNIX Specification (Spec 1170) - Four Volume Set , available
    from X/Open Company Ltd., X/Open Document Number T403. The set is four
    documents published solely in electronic form:

    o   System Interfaces and Headers, Issue 4 Version 2. Spec 1170 V1 , X/Open
        Document Number S418.
    o   Commands and Utilities, Issue 4 Version 2. Spec 1170 V2 , X/Open
        Document Number S419.
    o   System Interface Definitions, Issue 4 Version 2. Spec 1170 V3 , X/Open
        Document Number S420.
    o   International Terminal Interfaces (XCURSES), I4. Spec 1170 V4 , X/Open
        Document Number S422.

Detailed syntactic and semantic descriptions for operating system services and
interfaces that are in common use across applications and operating systems.
Including networking interfaces based on BSD Sockets.

2.  POSIX 1003.12 Draft 4.0 Part XX: Protocol Independent Interfaces (PII),
    available from the Institute of Electrical and Electronics Engineers
    (IEEE).

    Specifies the protocol independent interface semantics with syntax
    definitions based on BSD sockets and X-Open XTI.

3.  IBM Anynet/2 Multi-Protocol Transport Services Socket/MPTS Programmer's
    Reference, IBM publication order number S96F-8637.

    Describes the OS/2 sockets API definitions.

4.  VTAM V3R4.2 Sockets over SNA User Guide, IBM publication order number
    SC31-6487.

    Describes how to use the Sockets over SNA function to run MVS and OS/2
    TCP/IP socket applications.

5.  Multiprotocol Transport Networking (MPTN) Architecture: Technical Overview,
    IBM publication order number GC31-7073.

    Gives an overview of the MPTN architecture.

6.  X/Open Preliminary Specification, Part 1: MPTN Access Node Overview,
    available from X/Open in company review.

    Provides the detail specifications for MPTN submitted to X-OPEN.

7.  NetBIOS V1 for TCP/IP for OS/2, IBM publication order number SC31-6122.

    Product user guide to the NetBIOS application on TCP/IP for OS/2.

8.  (IETF) RFC 1001, Protocol Standard for NetBIOS Services on a TCP/UDP
    Transport, Concepts and Methods,

    Describes the architecture for NetBIOS on TCP/IP.

9.  (IETF) RFC 1002, Protocol Standard for NetBIOS Services on a TCP/UDP
    Transport, Detailed Specifications

    Provides the protocol format specifications for NetBIOS on TCP/IP.

10. AIX Version 3.2 Communication Programming Concepts, IBM publication order
    number SC23-2206.

    Provides overview and other technical references for sockets.


ΓòÉΓòÉΓòÉ 13.8. System Management References ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.8.1. Reliability, Availability and Serviceability Reference ΓòÉΓòÉΓòÉ

1.  (OS/2) FFST/2 Administration Guide, IBM publication order number S96F-8593.

    How the FFST/2 product is used by an OS/2 administrator.

2.  Writing a Device Driver for AIX Version 3.2, IBM publication order number
    GG24-3629.

    Examples of how to use the RAS facilities of AIX.

3.  (AIX/6000) InfoExplorer User's Guide and Reference, IBM publication order
    number SC23-2455.

    Guide on how to view all of the AIX user and programming documentation
    using the InfoExplorer program. This can be used to find out about how to
    use the AIX RAS facilities, such as error logging, trace and dump.

4.  (AIX) Problem Solving Guide and Reference, SC23-2204.

    Customer document for performing PD/PSI for AIX.

5.  (DCE) OSF DCE-RFC 24.1 Serviceability Proposal, available from OSF.

    How to use DCE logging facilities.

6.  OS2 LAN Server Problem Determination Guide, IBM publication order number
    S96F-8431.

    PD/PSI guide for LAN Server environment.


ΓòÉΓòÉΓòÉ 13.8.2. Software Management References ΓòÉΓòÉΓòÉ

1.  (AIX)  General Programming Concepts, Volume 1: Writing Programs, IBM
    publication order number SC23-2533.

    Describes how an application developer can use installp to install an
    application on AIX/6000 system. Chapter 20 is  Packaging Software for
    Installation as Optional Software

2.  CID Enablement Guidelines, IBM publication order number S10H-6666.

    Describes how to CID enable an OS/2, DOS, and Windows applications.

3.  CID Enablement of DOS Local Area Networks, IBM publication order number
    SC31-6833.

    Describes what an application must do to be CID enabled in Appendix D:
    Product Enablement. CID enablement is described for both DOS and OS/2
    applications.

4.  (OS/2)  Automated Installation for CID Enabled Extended Services, LAN
    Server V3.0 and Network Transport Services/2, IBM publication order number
    GG24-3781.

    Describes how to setup code server and remotely install Local Area
    Networks, and NTS/2.

5.  (AIX) NetViewDM/6000 Concepts, IBM publication order number GH19-5001.

    Describes the NetViewDM/6000 distribution product.

6.  POSIX, P1378.2 Draft 12, March 1994, Software Administration, available
    from the Institute of Electrical and Electronics Engineers (IEEE).

    Describes the POSIX proposal for software management commands and software
    packaging.

7.  Software Installer for OS/2 , is available on The Developer Connection for
    OS/2.

    IBM's software install development tool for OS/2 applications.

8.  Software Installer for Windows, is available on The Developer Connection
    for OS/2.

    IBM's software install development tool for Windows applications.


ΓòÉΓòÉΓòÉ 13.8.3. License Management References ΓòÉΓòÉΓòÉ

1.  (AIX/6000) NetLS Quick Start Guide, IBM publication order number SC09-1661.

    How to install the NetLS runtime and how to get started.

2.  (AIX/6000) Managing Software Development with the Network License System,
    IBM publication order number SC09-1660.

    The programmer's guide containing the license enablement APIs and
    explanations.

3.  (AIX/6000) Managing NCS Software, IBM publication order number SC09-1834.

    Explains Network Computing System (NCS), what is required for NCS, and how
    to setup NCS on your LAN.


ΓòÉΓòÉΓòÉ 13.8.4. Performance Monitoring References ΓòÉΓòÉΓòÉ

1.  Memory Debugging for C and C++ Programs, available on the The Developer
    Connection for OS/2.

    Provides design and programming recommendations, memory debugging tool
    information, and detection and solution examples.

2.  Requirements for Performance Instrumentation of DCE RPC and CDS Services,
    available as RFC 32.0 from OSF.

    Defines the performance instrumentation requirements for DCE, specifically
    RPC and CDS.

3.  (OS/2) SPM/2 User's Guide and Reference, included as part of the SPM/2
    online product documentation.

    Describes the SPM/2 in general with specific sections on using the SPM API,
    instrumenting and registering user metrics, and monitoring a network
    including instrumenting an agent for user applications.

4.  AIX/6000 Performance Tuning Guide, IBM publication order number SC23-2613.

    Description of the AIX/6000 Trace facility, including the MACROS for
    instrumenting users code.

5.  AIX Performance Toolbox/6000 User's Guide, IBM publication order number
    SC23-2579.

    Discussion of the xmperf capability to display and report user metrics.
    Also describes the Remote Statistics Interface (RSI) API and the System
    Performance Measurement Interface (SPMI) API.

6.  AIX System Performance Measurement Interface (SPMI) Programmer's Guide, IBM
    publication order number SC23-2556.

    Describes the AIX/6000 SPMI API with which a user can register metrics with
    AIX/6000, for subsequent reporting by xmperf.

7.  Writing a Device Driver for AIX Version 3.2, IBM publication order number
    GG24-3629.

    Describes the use of the AIX/6000 Trace Facility.


ΓòÉΓòÉΓòÉ 13.8.5. Remote System Management Access References ΓòÉΓòÉΓòÉ

1.  IBM Transmission Control Protocol / Internet Protocol Version 2.0 for OS/2,
    IBM publication order number SC31-6077.

    Describes how to use the Distributed Program Interface (DPI) on OS/2 to
    develop systems management subagents.

2.  Desktop Management Interface Specification Draft 4.4 Desktop Management
    Task Force, 1994, available via anonymous ftp from aurora.intel.com or
    gatekeeper.dec.com in directory "./pub/dmtf".

    Defines the rules for describing and obtaining management information for
    the hardware and software components of desktop computers.

3.  RFC 1156 (IETF): The Management Information Base (MIB).

    Defines the minimum set of variables, testpoints and controls which  a
    complete TCP/IP implementation is expected to support.

4.  RFC 1157 (IETF): Simple Network Management Protocol (SNMP).

    Defines the legal interactions which may occur under SNMP and the contents
    and structure of SNMP packets.


ΓòÉΓòÉΓòÉ 13.9. Extended Operating System References ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ 13.9.1. Naming References ΓòÉΓòÉΓòÉ

1.  DCE Application Developer's Guide, Open Software Foundation, version 1.0.3,
    available from the Open Software Foundation.

    Provides an overview of the DCE directory services and interfaces and a
    detailed description of the programming model for DCE applications.

2.  X/Open DCE: Directory Services Preliminary Specification, June 1994,
    available from X/Open Document Number P314, ISBN 1-85912-012-1.

    An overview of the DCE directory services and interfaces and, detailed
    syntactic and semantic descriptions of the DCE directory API calls.

3.  X/Open DCE: Remote Procedure Call Preliminary Specification, January 1994,
    available from X/Open Company Ltd., X/Open Document Number P312, ISBN
    1-872630-95-2.

    An overview of the DCE remote procedure call services and interfaces, and
    detailed syntactic and semantic descriptions of the DCE remote procedure
    call name service API calls.

4.  OSI-Abstract-Data Manipulation API (XOM), available from X/Open Company
    Ltd., X/Open Document Number C180, ISBN 1-872630-17-0.

    Describes object management interfaces for use with XDS.

5.  API to Directory Services (XDS)(covers X.500), available from X/Open
    Company Ltd., X/Open Document Number C190, ISBN 1-872630-18-9.

    An overview of the XDS directory services and interfaces and, detailed
    syntactic and semantic descriptions of the XDS directory API calls.

6.  X/Open Federated Naming Preliminary Specification, available from X/Open
    Company Ltd., 2H94, currently in company review.

    An overview and detailed syntactic and semantic descriptions of the
    Federated Naming services, protocols, and interfaces, and a description of
    the federated naming policy.

7.  OMG Joint Object Services Specification: Naming, May 1993, available from
    OMG Document Number 93.95.2.

    An overview and syntactic and semantic descriptions of the OMG object
    naming interfaces.

8.  OS/2 LAN Server 3.0 Application Programmer's Reference, IBM publication
    order number S96F-8440.

    Detailed syntactic and semantics descriptions for OS/2 LAN Server services
    and interfaces for Net*.

9.  OSF DCE Administration Guide, Module 1. Planning, Configuring, and Starting
    Up DCE, Appendix A: The DCE Cell Namespace, available from OSF.

    Layout and description of the DCE namespace.

10. DCE Cell Directory Service Usage Guidelines, available as DCE RFC 44.0 from
    OSF.

    Guidelines for namespace usage based on OSF DCE Administration Guide and
    Hewlett-Packard's experimentation.


ΓòÉΓòÉΓòÉ 13.9.2. Printing References ΓòÉΓòÉΓòÉ

1.  OS/2 2.0 Technical Library, Programming Guide Volume III, Chapter 18, Print
    Job Submission and Manipulation, IBM publication order number S10G-6495.

    Provides information and code examples to enable the application developer
    to start writing source code using the functions in the application
    programming interface of the OS/2 2.0 operating system.

2.  OS/2 2.0 Technical Library, Presentation Manager Programming Reference
    Volume I, Chapter 2 and 7, IBM publication order number S10G-6264.

    Describes the OS/2 printing APIs.

3.  IBM International Technical Support Centers, OS/2 Version 2.0, Volume 5:
    Print Subsystem, IBM publication order number GG24-3775.

    Describes the Print Subsystem component of OS/2 Version 2.0.

4.  OS/2 LAN Server 3.0 Application Programmer's Reference, IBM publication
    order number S96F-8440.

    Describes the DosPrint, Dev, SplQm and Spl APIs supported by IBM's OS/2 LAN
    Server.

5.  AIX Version 3.2 Commands Reference, Volume 2, IBM publication order number
    GC23-2366.

    Describes the AIX printing CLIs.

6.  AIX Version 3.2 Commands Reference, Volume 3, IBM publication order number
    GC23-2367.

    Describes the AIX printing CLIs.

7.  Printing for Fun and Profit Under AIX V3, IBM publication order number
    GC24-3570.

    Describes the Print Subsystem component of AIX/6000.


ΓòÉΓòÉΓòÉ 13.10. Graphical User Interface References ΓòÉΓòÉΓòÉ

1.  Object Technology In Application Development, IBM publication order number
    GG24-4290.

    Provides an overview of object-oriented programming.

2.  SOMobjects Developer Toolkit Publications, IBM publication order number
    S96F-8649.

    Provides programming information for SOM.

3.  Experiences with SOMobjects: Distributed System Object Model (DSOM), IBM
    publication order number GG24-4165.

    Provides information on Distributed SOM.

4.  Object-Oriented Interface Design: IBM Common User Access Guideline,1992,
    Que Corporation: Carmel, IN., ISBN 1-56529-170-0 or IBM publication order
    number SC34-4399.

    Presents the CUA design guide and CUA reference.


ΓòÉΓòÉΓòÉ 13.11. Development Tool Delivery References ΓòÉΓòÉΓòÉ

1.  The LAN Systems API Roadmap:  An Inventory, available on The Developer
    Connection for LAN Systems.

    This document describes the API's for the LAN Systems APIs.

2.  Developer Connection Product Submission Guidelines available on the The
    Developer Connection for LAN Systems.

    This document describes the process for getting tools and applications on
    to the The Developer Connection for LAN Systems.

3.  SOMobjects Developer Toolkit Publications, IBM publication order number
    S96F-8649.

    Provides programming information for SOM.


ΓòÉΓòÉΓòÉ 13.12. Customer Information References ΓòÉΓòÉΓòÉ

1.  Object-Oriented Interface Design: IBM Common User Access Guideline,1992,
    Que Corporation: Carmel, IN., ISBN 1-56529-170-0 or IBM publication order
    number SC34-4399.

    Provides definitions and guidelines applicable to online information units.

2.  Information Development Guidelines: Online Helps and Messages for Products
    Using OS/2 Information Presentation Facility , IBM publication order number
    SC26-3391.

    Provides style guidelines for online helps and messages produced with IPF.

3.  The Chicago Manual of Style, University of Chicago Press, ISBN 0-226-10390.

    Provides style guidelines for written information and is the basis for IBM
    style guidelines.

4.  ISO 8879: 1986, Information Processing - Text and Office Systems - Standard
    Generalized Markup Language (SGML), International Organization for
    Standardization, Geneva/New York.

    Describes the official standard definition of SGML.

5.  The SGML Handbook, by Charles F. Goldfarb, 1990, Oxford University Press.

    Provides an annotated and cross-referenced presentation of the Standard
    Generalized Markup Language (SGML) standard ISO8879.

6.  SGML: The Users' Guide to ISO8879, by Joan M. Smith and Robert Stutely,
    1988, Horwood/Halsted, Chichester/New York.

    Provides a guide and index to the Standard Generalized Markup Language
    (SGML) standard ISO8879.

7.  IBM Dictionary of Computing, McGraw-Hill, Inc.

    Provides over 22,000 entries that spans the full range of IBM's hardware
    and software products plus entries from industry standards.


ΓòÉΓòÉΓòÉ 13.13. Usability References ΓòÉΓòÉΓòÉ

1.  IBM Guide to Software Usability, by Kathleen Snyder, IBM publication order
    number SC26-3000.

    IBM-written summary of usability engineering techniques applied to software
    development.

2.  Tog on Interface, by Bruce Tognazzini, 1992, Addison-Wesley Publishing
    Company: Reading, MA.

    Designing user interfaces, by a software engineer who came to value the
    tenets of usability engineering.

3.  Principles and Guidelines in Software User Interface Design, by Deborah J.
    Mayhew, 1992, Prentice Hall: Englewood Cliffs, NJ.

    Practical, applicable, empirically-based guidelines for designing usable
    user interfaces.

4.  Usability Engineering, by Jacob Nielsen, 1993, Academic Press Cambridge,
    MA.

    Summary of usability engineering methods.

5.  Cost-Justifying Usability, by R.G. Bias and D.J. Mayhew (Eds.), 1994,
    Academic Press: Cambridge, MA.

    Describes how to apply cost-benefit analysis to usability engineering.

6.  Usability Inspection Methods, by J. Nielsen and R.L. Mack (Eds.), 1994,
    Wiley Sons, Inc.: New York.

    Provides a summary of a variety of ways to assess the usability of user
    interfaces without testing subjects.

7.  Object-Oriented Interface Design: IBM Common User Access Guideline, 1992,
    Que Corporation: Carmel, IN., ISBN 1-56529-170-0 or IBM publication order
    number SC34-4399.

    Presents the CUA design guide and CUA reference.

8.  The Visual Display of Quantitative Information, by E.R. Tufte, 1983,
    Graphics Press: Cheshire, Connecticut.

    Provides accessible guidelines for the use of color, graphs, tables, and
    other visual display of variables.