IBM OPERATING SYSTEM/2 (TM) TOOLKIT AND TECHNICAL REFERENCE
Contents


Announcement Letter Number ZP87-4076 dated April 2, 1987
Europe Middle East Africa - Last Revised on April 2, 1987



Brief Description of Announcement, Charges, and Availability

Customer Letter Section


*****************************************************************
*                                                               *
*  IBM SOFTWARE PRODUCT INFORMATION             APRIL 87        *
*                                                               *
*  IBM SOFTWARE PRODUCT INFORMATION                             *
*                                                               *
*  IBM SOFTWARE PRODUCT INFORMATION                             *
*                                                               *
*****************************************************************
*                                                               *
* This document is provided as general customer information     *
* only. IBM products and services which are announced and       *
* available in your country can be ordered under the applicable *
* standard agreements, terms, conditions and prices in effect   *
* at the time. For further information please contact your      *
* local IBM representative.                                     *
*                                                               *
*****************************************************************
=================================================================
                                                        ZP87-4076
IBM OPERATING SYSTEM/2 (TM) TOOLKIT AND TECHNICAL REFERENCE
PRODUCT DESCRIPTION
HIGHLIGHTS
o   Toolkit functions  that improve  programmer productivity  for
    creating IBM Operating System/2 applications
    -   Presentation  Interface   tools  to   assist  in   screen
        generation in a graphics and windowing environment
    -   Documented  sample  programs,   which  illustrate  useful
        programming techniques
    -   Programming aids  for IBM Macro  Assembler/2 and  IBM C/2
        Compiler, and message preparation utilities
o   IBM  Operating   System/2  Technical   Reference  Manual   is
    separately purchasable.
DESCRIPTION
The   IBM  Operating   System/2   Toolkit  contains   significant
programmer  productivity  functions  for   the  creation  of  IBM
Operating  System/2  mode  and   Family  applications.   The  IBM
Operating System/2 Toolkit, V1.0, contains the tools described in
this  Announcement Letter,  except for  the Presentation  Manager
tools. The IBM Operating System/2 Toolkit, V1.1, contains all the
Toolkit tools. Although the Linker  is packaged the IBM Operating
System/2, Linker  information is contained  in the  IBM Operating
System/2   Technical  Reference   and   IBM  Operating   System/2
Programmer Toolkit publications.
The IBM Operating  System/2 Toolkit contains the  following major
components:
o   Presentation  Manager  tools.  Used to  create  graphics  and
    windowing screens for interaction between application and end
    user.
o   IBM Operating System/2 Linker description.
o   Link  Related  Functions.   Includes   the  Import  Librarian
    (IMPLIB)  for  creating  import libraries,  and  tools  (BIND
    utility  and  appropriate  library)  for  creating  a  Family
    application.
o   Sample Programs.   Used to illustrate IBM  Operating System/2
    programming  features  and  IBM  Operating  System/2  Toolkit
    utilities.
o   Programming  Aids  for  IBM Macro  Assembler/2  and  IBM  C/2
    Compiler  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 which is
        accessible by an application.
    -   Bind messages to an executable module for fast access.
o   Toolkit publications.
The IBM Operating System/2 Technical Reference Manual is seperately
available  and  contains technical  information  which  supplements
information  in  the  IBM  Operating  System/2  and  IBM  Operating
System/2 Toolkit publications.  The Technical Reference Manual is a
prerequisite for some topics discussed in the Toolkit publications,
but  is  not included  in  the  IBM Operating  System/2  Programmer
Toolkit.
The  announcement of  IBM Operating  System/2, contains  additional
information on IBM Operating System/2 topics, such as 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.   The  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   Dialogue Editor.  Used to design a  dialogue box on the display
  screen.  The dialogue  box is  a  pop-up or  child window  that
  contains one or more window controls.  An application can use a
  dialogue 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  or IBM Operating
  System/2  Toolkit.  The  size  of the  icon  or  cursor can  be
  changed.
o   Font Editor  - Used  to create application  font files.   A 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 dialogue 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.3. In each environment the Linker can create an execution
module for either:
o   IBM Operating System/2 environment or DOS environment
o   DOS Version 3.3.
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  utilisation, 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 name 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.
The Linker subsequently uses import  library information to resolve
external references  to dynamic link  modules; the  Linker includes
the necessary dynamic link information in an application executable
module.
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.3.
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  an 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  Operating
System/2 DOS environment  or DOS Version 3.3  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.3. It is  anticipated that  most Family
applications  will  be run  in  either  an IBM  Operating  System/2
environment or in a DOS Version 3.3 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 Programmer  Toolkit  contains  sample
programs  written for  IBM  Macro Assembler/2  and  IBM C/2.  These
well-documented  examples  illustrate  the  use  of  IBM  Operating
System/2 programming features and IBM Operating System/2 Programmer
Toolkit utilities. The sample programs demonstrate the:
o   Programming  techniques for  the  Presentation  Manager in  the
  supported languages
o   Application build process  for IBM Operating System/2  mode 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  Technical Reference Manual  as a
reference manual.
PROGRAMMING AIDS FOR MACRO ASSEMBLER AND C LANGUAGES
The IBM  Operating System/2 Programmer  Toolkit contains  files for
IBM Operating System/2  using the IBM Macro Assembler/2  or the IBM
C/2 compiler. 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 puts 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.
Other  Toolkit  publications  discuss information  on  the  Systems
Application  Architecture  Common  User  Access  which  allows  the
application  developer to  develop applications  with a  consistent
user   interface.     Topics   include:    screen   layout,    Help
implementation, key assignments and window usage.
Toolkit publications are not available separately.
All IBM  Operating System/2 Programmer Toolkit,  V1.0, publications
will be revised for V1.1 to include Presentation Manager topics.
Part numbers  for IBM Operating  System/2 Programmer  Toolkit, V1.0
and V1.1 will be provided prior to general availability.
TECHNICAL REFERENCE MANUAL
The  IBM Operating  System/2  Technical  Reference Manual  contains
technical  information which  supplements  information  in the  IBM
Operating System/2  and IBM  Operating System/2  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 Technical  Reference manuals,  V1.0 and
V1.1 are seperately available for a charge, and are not included in
the IBM Operating System/2 Programmer Toolkits.
Part numbers  for the  IBM Operating  System/2 Technical  Reference
Manuals  V1.0   and  V1.1  will   be  provided  prior   to  general
availability.
SYSTEMS APPLICATION ARCHITECTURE
The  IBM  Operating  System/2  Programmer  Toolkit  is  an  initial
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
communication  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 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 Toolkit,  V1.0, contains  all the  IBM
Operating  System/2 Programmer  Toolkit functions,  except for  the
Presentation Manager  tools. The IBM Operating  System/2 Programmer
Toolkit,  V1.1,  contains  all IBM  Operating  System/2  Programmer
Toolkit functions.
The following announcements discuss other System Extensions for IBM
Operating System/2:
o   IBM C/2
o   IBM FORTRAN/2
o   IBM Pascal Compiler/2
o   IBM Basic Compiler/2
o   IBM Macro Assembler/2
o   IBM COBOL/2
o   IBM Operating System/2 Graphics Development Toolkit
The IBM  Personal Computer Software Overview  announcement contains
information  on  additional  IBM  Personal  Computer  products  and
announcement letters.
TECHNICAL INFORMATION
SPECIFIED OPERATING ENVIRONMENT
HARDWARE 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.5 MB of memory when
    configured to  run only IBM Operating  System/2 applications,
    and 2 MB 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 or 339(1)
    -   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(2)
o   One diskette drive (high capacity, either 5.25 inch 1.2 Mb or
    3.5 inch 1.44 Mb)
o   One fixed disk drive
--------------
1   Registered Trademark of IBM Corporation.
2   Trademark of IBM Corporation.
o   Keyboard
o   Display adapter and associated display
For device  specific information, see  the announcement of  the IBM
Operating System/2.
PROGRAMMING REQUIREMENTS  The  IBM  Operating  System/2  Programmer
Toolkit requires the IBM Operating System/2 (at same release level)
and accompanying manuals.
PREREQUISITES: IBM  Operating System/2 Technical Reference  (at the
same release level) is a prerequisite.
PLANNING INFORMATION
CUSTOMER RESPONSIBILITIES: The customer should:
o   Confirm  that  the Diskette  Drive  "A"  is the  same  capacity
  (5.25 inch 1.2 Mb  or 3.5 inch  1.44 Mb) as  the IBM  Operating
  System/2 Programmer Toolkit diskettes.
o   Ensuring that  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 Toolkit  on fixed disk using the
  IBM Operating System/2 Installation Aid  or as described in the
  IBM Operating System/2 Programmer Toolkit Programmer Guide.
INSTALLABILITY: The  IBM Operating System/2 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.
o   Copies the appropriate programs,  libraries, and utilities from
  the distribution diskettes on to the TOOLKIT sub-directories.
o   Creates a History File.
o   Adds the  IBM Operating  System/2 Programmer  Toolkit utilities
  and  batch files  to  the "Start  a Program"  list  of the  IBM
  Operating System/2.
IBM Operating  System/2 Programmer Toolkit installation  displays a
series of panels directing the  installation process.  The end-user
can choose  to install all  or selected  tools, such as  the Family
Application Programming  Interface Tools,  the sample  programs, or
the Interactive  Interface. Tools  not initially  installed can  be
installed later using the Installation Aid.
The IBM Operating System/2 Programmer Toolkit installation 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. If either  or both files are missing, a
warning message is displayed, and the  files can then be optionally
loaded from an IBM Operating System/2 distribution diskette.
The  installation process  uses a  IBM  Operating System/2  Toolkit
installation  profile  that  is  contained  on  the  IBM  Operating

System/2  Programmer   Toolkit  distribution   diskettes.   Further
information  on  the  Installation  Aid is  available  in  the  IBM
Operating System/2  User Reference Manual,  which is  packaged with
IBM Operating System/2.
PACKAGING: The IBM Operating System/2  Programmer Toolkit, V1.0, is
distributed with:
o   Diskettes.  The same IBM  Operating System/2 Programmer Toolkit
  machine readable information  is on 5.25 inch (1.2  Mb) and 3.5
  inch (1.44 Mb) diskettes.
o   IBM Operating System/2 programmer guide.
Packaging  information for  the IBM  Operating System/2  Programmer
Toolkit, V1.1, will be described when the general availability date
of the IBM Operating System/2 Programmer Toolkit, V1.1 is announced
in 4Q87.
SECURITY, AUDITABILITY, AND CONTROL
The   user   is   responsible  for   evaluation,   selection,   and
implementation of security features, administrative procedures, and
appropriate  controls  in  application  systems  and  communication
facilities.
                                                    1886W  9  001
                *****   END OF DOCUMENT   *****