* 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. *
IBM OPERATING SYSTEM/2 (TM) TOOLKIT AND TECHNICAL REFERENCE
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 aids for IBM Macro Assembler/2 and IBM C/2
Compiler, and message preparation utilities
o IBM Operating System/2 Technical Reference Manual is
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
o Presentation Manager tools. Used to create graphics and
windowing screens for interaction between application and end
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
o Sample Programs. Used to illustrate IBM Operating System/2
programming features and IBM Operating System/2 Toolkit
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
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
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
The following Presentation Manager components support windowing and
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
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
o Resource Compiler. Used to compile resources (such as icons,
cursors, menus and dialogue box templates) and place them in
the applications resource file.
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
The linker supports dynamic files, compression of executable files,
and module definition files for IBM Operating System/2 executable
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
o No need to relink when external routines are changed or
o Potentially improved performance, since inactive segments (such
as exception processing routines) would be loaded only when
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
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
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
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
o Application build process for IBM Operating System/2 mode and
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
o Development of IBM Operating System/2 DOS and Family
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
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
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
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
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.
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 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
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
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
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
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
The following announcements discuss other System Extensions for IBM
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
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 Display adapter and associated display
For device specific information, see the announcement of the IBM
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.
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
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
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
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
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
1886W 9 001
***** END OF DOCUMENT *****