IBM OPERATING SYSTEM/2 (TM) STANDARD EDITION PROGRAMMER TOOLKIT AND
TECHNICAL REFERENCE

Contents


Announcement Letter Number 287-105 dated April 2, 1987
US - Last Revised on April 2, 1987



Brief Description of Announcement, Charges, and Availability

       The IBM Operating System/2 Standard Edition Programmer Toolkit
improves programmer productivity when developing IBM Operating
System/2 and Family applications.  The IBM Operating System/2
Standard Edition Programmer Toolkit Version 1.0 contains tools for
creating dynamic link libraries and Family applications, sample
programs, and other programming aids.  The IBM Operating System/2
Standard Edition Programmer Toolkit Version 1.1 additionally contains
tools for creating alphameric and graphics applications in a
windowing environment.  Each IBM Operating System/2 Standard Edition
release has a corresponding Technical Reference available separately.
Each of these is a prerequisite for the respective IBM Operating
System/2 Standard Edition Programmer Toolkit.
 (TM) Trademark of International Business Machines Corporation.
Program                                           One-Time
Number         Program Name                         Charge
6280200        IBM Operating System/2
                  Standard Edition
                  Programmer Toolkit
                  Version 1.0                         $750
6280201        IBM Operating System/2
                  Standard Edition
                  Technical Reference
                  Version 1.0                          200
6280211        IBM Operating System/2
                  Standard Edition
                  Programmer Toolkit
                  Version 1.1                          750
6280212        IBM Operating System/2
                  Standard Edition
                  Technical Reference
                  Version 1.1                          200
       Planned Availability:  First quarter 1988 for IBM Operating
System/2 Standard Edition Programmer Toolkit Version 1.0 and IBM
Operating System/2 Standard Edition Technical Reference Version 1.0.
       The availability for IBM Operating System/2 Standard Edition
Programmer Toolkit Version 1.1 and IBM Operating System/2 Standard
Edition Technical Reference Version 1.1 will be announced in fourth
quarter 1987.


Customer Letter Section

HIGHLIGHTS
o   Toolkit functions help improve programmer productivity for IBM
    Operating System/2 applications
    -   Presentation Manager tools to assist in screen generation in
        a graphics and windowing environment
    -   Tools for creating dynamic link libraries and Family
        applications
    -   Documented sample programs, which illustrate useful
        programming techniques
    -   Programming aids for IBM Macro Assembler/2 and IBM C/2, and
        message preparation utilities
o   IBM Operating System/2 Standard Edition Technical Reference is
    available separately.
DESCRIPTION
       The IBM Operating System/2 Standard Edition Programmer Toolkit
contains significant programmer productivity functions for the
creation of IBM Operating System/2 and Family applications.  IBM
Operating System/2 Standard Edition Programmer Toolkit Version 1.0
contains the tools described in this announcement, except for the
Presentation Manager tools.  IBM Operating System/2 Standard Edition
Programmer Toolkit Version 1.1 contains all the tools.  Although the
Linker is packaged with IBM Operating System/2, Linker information is
contained in the IBM Operating System/2 Technical Reference and IBM
Operating System/2 Standard Edition Programmer Toolkit publications.
       The IBM Operating System/2 Standard Edition Programmer Toolkit
contains the following major components:
o   Presentation Manager tools.  Used to create graphics and screen
    windows for interaction between application and end user.
o   Link Related Functions.  Includes the IBM Operating System/2
    Linker description, Import Librarian (IMPLIB) for creating import
    libraries, and the appropriate tools (BIND utility and Family
    Application Program Interface library) to create a Family
    application.
o   Sample Programs.  Used to illustrate IBM Operating System/2
    programming features and IBM Operating System/2 Standard Edition
    Programmer Toolkit utilities.
o   Programming Aids for IBM Macro Assembler/2 and IBM C/2 Languages.
    Contains files of macro libraries, declarations and error equates
    which enhance programmer productivity.
o   Message Preparation Utilities.  Used to:
    -   Convert a source message file to an indexed file accessible
        by an application.
    -   Bind messages to an executable module for fast access.
o   Publications.
       The IBM Operating System/2 Standard Edition Technical
Reference contains technical information which supplements
information in the IBM Operating System/2 and IBM Operating System/2
Standard Edition Programmer Toolkit publications.  The Technical
Reference is available separately.  It is not included in the IBM
Operating System/2 Standard Edition Programmer Toolkit, but is a
prerequisite for understanding some topics discussed in the Toolkit
publications.
       Programming Announcement 287-099, dated April 2, 1987,
contains additional information on IBM Operating System/2 topics,
such as the IBM Operating System/2 environment and the DOS
environment.
PRESENTATION MANAGER TOOLS
The Presentation Manager has windowing and graphics functions which
offer the programmer new capabilities for developing IBM Operating
System/2 applications.  Multiple applications can be simultaneously
displayed via overlapping screen windows, and each application can
support one or more windows.  The end user can dynamically control
the window size and position, and scroll the data inside a window.
Data can be moved or copied from one window to another window in the
same or a different application.
       Extensive graphics functions support All Points Addressable
devices:  displays, printers, and plotters.  An IBM Operating
System/2 application can draw graphics data on screen windows or
display the equivalent data using bitmaps.  A bitmap, which is used
to produce rapid changes on a screen, is similar to the screen image
but is created in memory.  The IBM Operating System/2 supports both
retained and non-retained graphics.  Retained graphics provide an
efficient method for building complex pictures that are drawn many
times with few changes.  Non-retained graphics can be used for fast
drawing of simple pictures.  An application can draw and fill
graphics objects, such as lines, arcs, font characters and images.
An application can specify various attributes, such as color, line
style and area fill pattern.  IBM Operating System/2 contains
graphics transformations to change the object's size, position and
orientation.  There are many text functions and standard fonts in a
variety of font styles and sizes.  Alphameric extensions allow for
loadable fonts and features, such as underscoring of individual
characters.
       The Presentation Manager tools assist in the development of
interactive, alphameric and graphics applications which support the
Systems Application Architecture guidelines.  These guidelines assist
the programmer in developing consistent, ease-of-use applications.
The standard graphics primitives support the Systems Application
Architecture and enable the interchange of graphics documents between
participating IBM processor families.  All Presentation Manager
utilities run in the IBM Operating System/2 environment.
       The following Presentation Manager components support
windowing and graphics:
o   Dialog Editor.  Used to design a dialog box on the display
    screen.  The dialog box is a pop-up or child window that contains
    one or more window controls.  An application can use a dialog box
    to prompt a user for additional information about a current
    command selection.
o   Icon Editor.  Used to create icons, cursors and bitmaps that are
    not predefined in IBM Operating System/2 Standard Edition or IBM
    Operating System/2 Standard Edition Programmer Toolkit.  The size
    of the icon or cursor can be changed.
o   Font Editor.  Used to create application font files.  An IBM
    Operating System/2 application can use a maximum of four fonts.
o   Include Files.  Used when compiling programs that need windowing
    capability.
o   Resource Compiler.  Used to compile resources (such as icons,
    cursors, menus and dialog box templates) and place them in the
    applications resource file.
LINKER:  A Linker is packaged in the IBM Operating System/2.  The
Linker can execute in any of these environments:  IBM Operating
System/2 environment, DOS environment in IBM Operating System/2, or
DOS Version 3.30.  In each environment the Linker can create an
executable module for either:
o   IBM Operating System/2 environment, or
o   DOS environment or DOS Version 3.30.
       The linker can create:
o   An application (program) executable module.  Input files are the
    compiled application source (i.e., object) files, a list of other
    object file libraries, import libraries, and an optional Module
    Definition File.
o   A dynamic link library with entry points which can be invoked
    under IBM Operating System/2.  Input files are compiled
    application source (i.e., object) files, and a Module Definition
    File.
       The Linker supports dynamic files, compression of executable
files, and module definition files for IBM Operating System/2
executable files.
       Linker options are operating system dependent.  Some options
are valid when creating executable files for both IBM Operating
System/2 and DOS environments.  Other options are valid when creating
executable files for only IBM Operating System/2 applications or only
DOS applications.
LINK RELATED FUNCTIONS
Dynamic linking is a significant IBM Operating System/2 feature which
allows routines to be linked with far-call references to external
libraries.  These far calls are bound during either the program load
or program execution time.
       To bind the far call at program load time, the application
developer specifies one or more libraries at link time.  These
libraries contain routines with special definition records which
satisfy the external references.  When the calling program is run,

the IBM Operating System/2 loads the dynamic link segments from the
specified modules and connects the calling program to the called
routines.  A linker option allows a delayed resolution until the
segment is needed.
       Different programming statements are used if the far call is
bound at the program execution time.  The application developer must
incorporate special system calls into the source code programs.
       Dynamic linking has many advantages:
o   Improved storage utilization, since the same common (object)
    library routines are not link-edited into many different
    executable modules.
o   No need to relink when external routines are changed or updated.
o   Potentially improved performance, since inactive segments (such
    as exception processing routines) would be loaded only when
    needed.
o   Shared dynamic link routines among many applications.  This
    allows the application developer to construct complex
    applications as dynamic link libraries.
o   Program initialization.  When a dynamic link library is loaded,
    it can optionally invoke an initialization routine, before any
    dynamic link routine is called.
IMPORT LIBRARIAN:  The Import Librarian IMPLIB automates the
importing of dynamic link references (both names and entry point)
into a dynamic link library.  IMPLIB takes a Module Definition File
and produces an import library.  Import libraries contain special
records which point to the target dynamic link libraries and entry
points.
FAMILY APPLICATION PROGRAM INTERFACE AND BIND UTILITY
A Family application runs on many system units, including many not
supported by IBM Operating System/2.  A Family application is an
executable module that runs in all three environments:  IBM Operating
System/2, DOS in IBM Operating System/2, and DOS Version 3.30.
       The developer creates a Family application as follows:
o   Writes an IBM Operating System/2 application source program with
    certain conventions.  For example, the source code must use the
    Family Application Program Interface, which is a subset of the
    IBM Operating System/2 Application Program Interface.
o   Compiles and links the program in IBM Operating System/2
    environment to obtain an executable module.
o   Uses the BIND utility and associated libraries to create a
    single, executable, Family module.
       The Family application contains the necessary CALL statements
for running in the IBM Operating System/2 environment and the
required interrupts and object libraries for running in the DOS
environment or DOS Version 3.30 environment.  A Family application
uses dynamic linking at load time when running in the IBM Operating
System/2 environment.
       There are two major advantages of a Family application.  The
first is reduced program development time and effort.  The programmer
develops the application only once, and is not concerned with system
function differences between operating systems.  System calls in the
IBM Operating System/2 environment do not always map one-for-one with
DOS interrupt functions.
       The second major advantage of a Family application is that the
application developer distributes one Family executable module
instead of separate executable modules for:  (a) an IBM Operating
System/2 environment, and (b) a DOS environment in IBM Operating
System/2 or DOS Version 3.30.  It is anticipated that most Family
applications will be run in IBM Operating System/2 environment or in
a DOS Version 3.30 environment.  The end user might choose for
migration purposes to run a Family application in the DOS
environment.
SAMPLE PROGRAMS
The IBM Operating System/2 Standard Edition Programmer Toolkit
contains sample programs written in IBM Macro Assembler/2 and IBM
C/2.  These documented examples illustrate the use of IBM Operating
System/2 programming features and IBM Operating System/2 Standard
Edition Programmer Toolkit utilities.  The sample programs
demonstrate the:
o   Programming techniques for the Presentation Interface in the
    supported languages.
o   Application build process for IBM Operating System/2 and Family
    applications
o   Use of dynamic link calls
o   Important features of the IBM Operating System/2 Application
    Program Interface.  Examples include:  process and thread
    creation, memory allocation, keyboard and other input/output
    mechanisms, device driver creation, input/output privilege level
    instructions, critical error handling, and code page switching.
o   Development of IBM Operating System/2 DOS and Family
    applications.
       The sample programs contain the files needed to compile, link,
and sometimes bind the complete application.  The sample programs are
referenced in the IBM Operating System/2 programmer guide.
       The sample program files contain batch files, which control
the build process.  This process constructs executable and library
sample program files.  The batch files are appropriately documented.
       The programmer can save development time by using Toolkit
features (such as sample programs and the programmer guide) as a
guide and using the IBM Operating System/2 Standard Edition Technical
Reference as a reference manual.
PROGRAMMING AIDS FOR MASM AND C LANGUAGES
The IBM Operating System/2 Standard Edition Programmer Toolkit
contains files for IBM Operating System/2 using the IBM Macro
Assembler/2 or IBM C/2.  The Toolkit files contain macro libraries or
system declarations for:
o   Input/output interface for displays, keyboard, and pointing
    device (mouse) subsystems
o   System error equates or definitions
o   Other system call macros and declarations
MESSAGE PREPARATION UTILITIES
These utilities give greater message processing flexibility to the
application developer.  Messages are initially in one or more
separate files.  These utilities incorporate messages into an
application.  Separate message files makes it easier to translate
messages into other languages, since the message length is not fixed.
       The Make Message File utility converts a source message file
into an indexed file for retrieval by the IBM Operating System/2
message retriever.  The Message Bind utility put messages in memory
with the application; it enhances performance by binding messages to
an existing executable application module.
       The IBM Operating System/2 uses these same routines to display
online text for help functions and error messages in both IBM
Operating System/2 and DOS environments.
TOOLKIT PUBLICATIONS
The IBM Operating System/2 programmer guide is a task-oriented
publication to the IBM Operating System/2 application development
process.  Topics include:  program design considerations, tools for
creating programs and libraries, program linking, Family application
creation, programming techniques illustrated in the sample programs,
message utility capabilities, subsystem creation, code page switching
techniques, device driver creation, and conversion of existing
applications.
       Toolkit publications are not available separately.
       All IBM Operating System/2 Toolkit Version 1.0 publications
will be revised for Version 1.1 to include Presentation Manager
topics.
TECHNICAL REFERENCE
The IBM Operating System/2 Standard Edition Technical Reference
contains technical information which supplements information in the
IBM Operating System/2 and IBM Operating System/2 Standard Edition
Programmer Toolkit publications.  This two-volume publication is a
prerequisite for the user of the IBM Operating System/2 Programmer
Toolkit, since Toolkit publications reference information contained
in the Technical Reference.
       Technical Reference topics include:  system architecture,
device driver architecture, System Application Program Interface,
input/output subsystems, and function and return call definitions.
Technical Reference information is not directly associated with the
IBM Operating System/2 Programmer Toolkit utilities and
documentation.
       The IBM Operating System/2 Standard Edition Technical

Reference Version 1.0 (6280201) is available separately for a charge.
It is not included in the IBM Operating System/2 Standard Edition
Programmer Toolkit.
       The IBM Operating System/2 Standard Edition Technical
Reference Version 1.1 (6280212) is available separately for a charge.
It is not included in the IBM Operating System/2 Standard Edition
Programmer Toolkit.
SYSTEMS APPLICATION ARCHITECTURE
The IBM Operating System/2 Standard Edition Programmer Toolkit is a
participant in IBM Systems Application Architecture, a collection of
selected software interfaces, conventions, and protocols whose
initial set is planned to be published in 1987.  IBM Systems
Application Architecture is to be the framework for development of
consistent applications across the future offerings of the major IBM
computing environments -- System/370, System/3X, and the IBM Personal
Computers.
       IBM Systems Application Architecture consists of four related
elements, two of which are new (Common User Access and Common
Programming Interface), plus extensions to today's existing
communications architectures (Common Communications Support).  IBM
Systems Application Architecture establishes the basis for Common
Applications, developed by IBM to be consistent across IBM systems.
       The IBM Operating System/2 Standard Edition Programmer Toolkit
participates in the following elements of IBM Systems Application
Architecture:
o   Common User Access
o   Common Programming Interface
    -   Presentation Interface
ADDITIONAL INFORMATION
The IBM Operating System/2 Standard Edition Programmer Toolkit
Version 1.0 contains all the IBM Operating System/2 Standard Edition
Programmer Toolkit functions, except for the Presentation Managers
tools.  The IBM Operating System/2 Programmer Toolkit Version 1.1
contains all IBM Operating System/2 Standard Edition Programmer
Toolkit functions.
       The following Programming Announcements contain information
regarding system extensions for IBM Operating System/2:
o   New Compilers and Assembler for IBM Personal Computers and IBM
    Operating System/2:  287-104, dated April 2, 1987
o   New Versions of IBM Graphics Development Toolkit:  287-106, dated
    April 2, 1987.
       The IBM Personal Computer Software Overview Programming
Announcement 287-095, dated April 2, 1987, contains additional
information on IBM Personal Computer products and announcement
letters.
EDUCATION SUPPORT
       The Atlanta Technical Education Center will include the
appropriate IBM Operating System/2 Standard Edition Programmer
Toolkit topics as part of the IBM Operating System/2 customer
education classes.  Details will be available at IBM Operating
System/2 availability.
SCHEDULE
       Planned availability of IBM Operating System/2 Standard
Edition Programmer Toolkit Version 1.0 and IBM Operating System/2
Standard Edition Technical Reference, Version 1.0 is first quarter
1988.  The planned availability date for IBM Operating System/2
Standard Edition Programmer Toolkit Version 1.1 and IBM Operating
System/2 Standard Edition Technical Reference Version 1.1 will be
announced in fourth quarter 1987.
TECHNICAL INFORMATION
SPECIFIED OPERATING ENVIRONMENT
MACHINE REQUIREMENTS:  The recommended minimum hardware configuration
for IBM Operating System/2 Programmer Toolkit is the same as for IBM
Operating System/2:
o   IBM Personal Computer system unit with 1.5MB of memory when
    configured to run only IBM Operating System/2 applications, and
    2MB of memory when configured to run both IBM Operating System/2
    and DOS applications.
    -   IBM Personal System/2 (Models 50, 60 or 80)
    -   IBM Personal Computer AT (R) (5170):  Models 099, 239, 319,
        or 339
    -   IBM Personal Computer AT (5170):  Model 068 with fixed disk
        to make the system unit equivalent to a Model 099.
    -   IBM Personal Computer XT (TM) (5162): Model 286
o   One diskette drive (high capacity)
o   One fixed disk drive
o   Keyboard
o   Display adapter and associated display
 (TM) Trademark of International Business Machines Corporation.
 (R) Registered trademark of International Business Machines
   Corporation.
       For device-specific information, refer to the IBM Operating
System/2 Programming Announcement 287-099, dated April 2, 1987.
PROGRAMMING REQUIREMENTS:  The IBM Operating System/2 Standard
Edition Programmer Toolkit requires the IBM Operating System/2 (at
same release level) and accompanying manuals.
PREREQUISITES:  IBM Operating System/2 Standard Edition Technical
Reference (at same release level).
PLANNING INFORMATION
CUSTOMER RESPONSIBILITIES:  The customer should:
o   Confirm that the Diskette A Drive is the same capacity (1.2MB or
    1.44MB) as the IBM Operating System/2 Standard Edition Programmer
    Toolkit diskettes.
o   Ensure that a fixed disk has enough free space.  The default disk
    is C.
o   Create a backup copy of the original IBM Operating System/2
    Programmer Toolkit diskettes.
o   Install IBM Operating System/2 Standard Edition Programmer
    Toolkit on the fixed disk using the IBM Operating System/2
    Installation Aid.
INSTALLABILITY:  The IBM Operating System/2 Standard Edition
Programmer Toolkit can be easily installed using the IBM Operating
System/2 Installation Aid.  The installation process:
o   Creates the subdirectory structure (TOOLKIT) on the designated
    fixed disk.  ("C" is the default.)
o   Copies the appropriate programs, libraries, and utilities from
    the distribution diskettes onto the TOOLKIT subdirectories.
o   Creates a History File.
o   Adds the IBM Operating System/2 Standard Edition Programmer
    Toolkit utilities and batch files to the Start a Program list of
    IBM Operating System/2.
       IBM Operating System/2 Standard Edition Programmer Toolkit
installation displays a series of panels directing the installation
process.  The end user may choose to install all or selected tools.
Tools not initially installed can be installed later using the
Installation Aid.
       IBM Operating System/2 Standard Edition Programmer Toolkit
installation also verifies the presence of two files (IBM Operating
System/2 Linker and the System Application Programming Interface)
which are shipped with the IBM Operating System/2 Standard Edition.
If either or both files are missing, a warning message is displayed,
and the files can then be optionally loaded from a IBM Operating
System/2 Standard Edition distribution diskette.
       The installation process uses a IBM Operating System/2
Standard Edition Programmer Toolkit installation profile that is
contained on the IBM Operating System/2 Standard Edition Programmer
Toolkit diskettes.  Further information on the Installation Aid is
available in the IBM Operating System/2 user reference, which is
packaged with IBM Operating System/2.
PACKAGING:  The IBM Operating System/2 Standard Edition Programmer
Toolkit Version 1.0 is distributed with:
o   Program License Agreement.
o   Diskettes.  The same IBM Operating System/2 Standard Edition
    Programmer Toolkit machine-readable information is on 5.25-inch
    (1.2MB) and 3.5-inch (1.44MB) diskettes.
o   IBM Operating System/2 programmer guide.
       Packaging information for IBM Operating System/2 Standard
Edition Programmer Toolkit Version 1.1 will be described at
availability of IBM Operating System/2 Standard Edition Programmer
Toolkit Version 1.1.
SECURITY, AUDITABILITY, AND CONTROL
       User management is responsible for evaluation, selection, and
implementation of security features, administrative procedures, and
appropriate controls in application systems and communication
facilities.
ORDERING INFORMATION
       Ordering instructions will be provided when the IBM Operating
System/2 Standard Edition Programmer Toolkit and Technical Reference
become available.
REPLACEMENT PROGRAM:  Licensees of IBM Operating System/2 Standard

Edition Programmer Toolkit Version 1.0 in the United States or Puerto
Rico are entitled to a free IBM Operating System/2 Standard Edition
Programmer Toolkit replacement at availability of IBM Operating
System/2 Standard Edition Programmer Toolkit Version 1.1.  Details
will be made available at the IBM Operating System/2 Standard Edition
Programmer Toolkit Version 1.1 availability.
       Owners of IBM Operating System/2 Technical Reference Version
1.0 in the United States or Puerto Rico are entitled to a free IBM
Operating System/2 Technical Reference replacement at availability of
IBM Operating System/2 Technical Reference, Version 1.1.  Details
will be made available at IBM Operating System/2 Technical Reference
Version 1.1 availability.
TERMS AND CONDITIONS
LICENSING:  These programs are licensed under the terms and
conditions of the IBM Program License Agreement.  A copy of the
agreement is included in the program package.
LIMITED WARRANTY:  Program Package:  Yes.  Media:  Three months.
PROGRAM SERVICES:  Central Service, including the IBM Support Center,
will be available until 12 months after availability of IBM Operating
System/2 Programmer Toolkit.  The statement of service included in
the program package will describe this service.
VOLUME DISCOUNT:  Volume discounting is available under the terms and
conditions of the Quantity Discount Agreement (QDA) for Personal
Computer Licensed Programs Exhibit (3580-8) and the Personal Computer
Licensed Programs for Qualified Educational Institutions/Hospitals
Exhibit (358E-7).  The programs are included in Category A under
5871-AAA.
TESTING PERIOD:  Two months for Program Packages acquired under a
QDA.
EDUCATIONAL ALLOWANCE:  A 55% educational allowance is available to
qualifying institutions.  This allowance is not additive to any other
discount or allowance.
CHARGES
PROGRAM                                           ONE-TIME
NUMBER         PROGRAM NAME                         CHARGE
6280200        IBM Operating System/2
                  Standard Edition
                  Programmer Toolkit
                  Version 1.0                         $750
6280201        IBM Operating System/2
                  Standard Edition
                  Technical Reference
                  Version 1.0                          200
6280211        IBM Operating System/2
                  Standard Edition
                  Programmer Toolkit
                  Version 1.1                          750
6280212        IBM Operating System/2
                  Standard Edition
                  Technical Reference
                  Version 1.1                          200