From: bjaspan@athena.mit.edu (Barry Jaspan)
Subject: OS/2 2.0 Frequently Asked Questions, Programmer's Edition 1.3
Followup-To: poster
Summary: This posting answers Frequently Asked Questions about
	programming and development under OS/2 2.0.  Read this before
	you post a question to the comp.os.os2.programmer newsgroup.
Supersedes: <os2-faq-prog_715809962@athena.mit.edu>
Organization: Massachvsetts Institvte of Technology
Date: Thu, 8 Oct 1992 16:05:00 GMT
Expires: Thu, 5 Nov 1992 16:04:50 GMT

Archive-name: os2-faq/prog
Version: 1.3

OS/2 2.0 Frequently Asked Questions, Programmer's Edition
Version 1.3, September 6, 1992
Compiled by Barry Jaspan, <bjaspan@athena.mit.edu>

This FAQ is for programming and development-related issues for OS/2
2.0.  It is freely distributable.  Direct all responses and questions
to bjaspan@athena.mit.edu.  Mention of a product does not constitute
an endorsement.  Answers to questions closer to the bottom of the list
may rely on information given in prior answers.  Customers outside the
United States should not necessarily rely on 800 telephone numbers,
part numbers, or upgrade policies contained in this list; all prices
are listed in United Stated dollars unless otherwise specified.
PLEASE CONTRIBUTE ANY INFORMATION YOU CAN.

Many of the answers below refer to anonymous ftp from FTP-OS2.NMSU.EDU
(128.123.35.151).  The name 'ftp-os2' is used as a shorthand to refer
to this machine.

Release Notes: This is a reposting of version 1.3, as I have not had
time to create a new version recently.

Questions addressed in this release:
	(a * indicates that no answer is available; all answers are
	currently incomplete)

1.  Languages, Compilers, Debuggers
----------------------------------------------------------------------

(1.1)	What programming languages come with OS/2 2.0?
(1.2)	What C/C++ development environments are available?
(1.3)	What are the differences between the two available versions of
	GNU C?
(1.4)	How can I view the GNU C documentation?
(1.5)	What other programming languages are available for OS/2?  (Esp.
        inexpensive ones.)
(1.6)	Which of these compilers can be used to generate PM apps?
(1.7)	What is REXX?  How do I write and run a REXX program?
(1.8)	What debuggers are available for OS/2?
(1.9)*	Where can I get documentation on the OBJ/LIB/EXE format used
	by OS/2 2.0? 
(1.10)*	Please summarize this information, and tell me what I need to
	do OS/2 development.
(1.11)  GCC/2 crashes with a trap when I try to compile a program.  Why?

2.  Tools, Toolkits, Accessories
----------------------------------------------------------------------

(2.1)	What programming editors are available for OS/2?
(2.2)	What programming tools/toolkits/accessories are available for OS/2?
(2.3)	What GNU tools are available and where can I find them?
(2.4)	Is a socket library available?  How can I use it?

3.  Programming, Porting
----------------------------------------------------------------------

(3.1)	How can I recompile public domain/shareware source code for OS/2?
(3.2)*	How can I port my DOS program to OS/2?
(3.3)*	How can I port my Windows program to OS/2?
(3.4)*	Is OS/2 suitable for real time programs?
(3.5)	How do I write an OS/2 device driver?
(3.6)	How can I simulate (Unix feature) under OS/2?
	(a)* fork
	(b)* fork/exec
	(c) select()
	(d)* job control
(3.7)*	How does programming PM compare to programming X?
(3.8)	Why doesn't printf() produce output when I expect it to?

4.  Documentation, Help
----------------------------------------------------------------------

(4.1)	Where can I get information on OS/2 APIs and programming?
(4.2)	Where can I get sample code?
(4.3)	Are there any OS/2 programming classes or seminars?
(4.4)	What are good reference books for programming in OS/2 and PM?
(4.5)	What are the OS/2 redbooks, and how do I get them?

5.  Miscellaneous
----------------------------------------------------------------------
(5.1)	What is available for multimedia programming under OS/2?
(5.2)*	What is available for AI/neural net programming under OS/2?

======================================================================

1.  Languages, Compilers, Debuggers
----------------------------------------------------------------------

(1.1)	What programming languages come with OS/2 2.0?

The original BASIC and BASICA (for systems with BASIC in ROM), DOS's
QBASIC, and OS/2's REXX come with OS/2 2.0.  See question #1.7 for
information on REXX.

(1.2)	What C/C++ development environments are available?

Many companies offer C or C++ compilers.  The following list is almost
guaranteed to be incomplete and somewhat inaccurate.

IBM Workset/2, 1-800-3-IBM-OS2, $895.  Includes the C Set/2 compiler,
the IPMD multithreaded PM debugger, the Workframe/2 development
environment, and the Developer's Toolkit (utilities and online
documentation).  These pieces are also available separately.  The full
product announcement is available on ftp-os2.  Bug reports for C Set/2
can be mailed to cset2@vnet.ibm.com, for Workframe/2 to
workframe@vnet.ibm.com and will go straight to the developers.  NOTE:
Workset/2 was available at a promotional rate of $295 in the US and
$399 in Canada, but the originally announced end dates have passed.  I
do not know if the promotion has been extended, so I assume it has
not.

Watcom C 9.0, (519) 886-3700.

JPI C and C++, (415) 967-3200 (USA), +44 234 267500 (UK/Europe), $180.

Glockenspiel C++, (+353)-1-733166.

Microway C++, $595.

GNU C.  Two flavors of the GNU C compiler are available, both on
ftp-os2.  GCC/2, based on GNU C 2.2.2, is in /pub/os2/2.0/programming/
gcc2-2.2.2, and emx/gcc is in /pub/os2/2.0/programming/emx-0.8d.  See
question #1.3 for information on the differences between the two.

(1.3)	What are the differences between the two available versions of
	GNU C?

The two versions of GNU C that are available were ported to OS/2 with
different goals and philosophies in mind and therefore have different
characteristics.  However, both systems include a fairly complete C
library and can be used to compile useful programs, although their
support of Unix-specific semantics differs.  Furthermore, both systems
are being actively developed and are constantly improving.

The goal of GCC/2 is to create a pure, freely redistributable OS/2 2.0
development environment with no extra baggage for backwards
compatibility; it is based on the assumption that DOS will die and is
not worth worrying about.  It is based on GNU C 2.2.2, supports C and
C++, and can create PM programs.  It produces "native" 32 bit .OBJ
files that are linked with OS/2's LINK386.EXE, and can be linked
together with .OBJ files produced by IBM C Set/2 and other compatible
compilers.  The mailing list os2gcc@charon.mit.edu exists for
discussion of this port; send mail to os2gcc-request@charon.mit.edu
for subscription information.

emx/gcc 0.8d, also based on GNU C 2.1, supports only C and can create
PM programs.  (emx/g++ is now available in beta release, and will
eventually be added to emx/gcc.)  emx's goal is to make porting Unix
programs easier by emulating Unix semantics as closely as possible.
It produces programs that can run both under OS/2 using EMX.DLL and
under DOS using the emx DOS extender.  emx/gcc uses standard Unix
development tools like ld and nm, and attempts to support Unix-isms
like select().  A version of gdb exists that can debug emx/gcc
programs.  An emx-related mailing list exists; send mail to
LISTSERV@ludd.luth.se with a subject of "help" for subscription
information.  (Note that this is a *NEW* address for the emx
discussion list.)

(1.4)	How can I view the GNU C documentation?

GNU C/C++ comes with documentation from the Free Software Foundation
in texinfo (.texi) format.  This documentation is about gcc in
general, and has no OS/2-specific information.

All utilities needed to compile/view/tex the texinfo files are readily
available for OS/2.  The GNU texinfo package, available on ftp-os2 in
pub/os2/all/gnu/gnuinfo.zoo, includes makeinfo.exe for compiling
texinfo, info.exe for viewing them, and texinfo.tex and texindex.exe
for TeXing them.

An ASCII text version of the gcc documentation is also available on
ftp-os2, in the file pub/os2/2.0/gnu/gcc21/gcctxt.zoo.

(1.5)	What other programming languages are available for OS/2?  (Esp.
        inexpensive ones.)

Virtually all of them: Assembler, COBOL, Pascal, Fortran, Smalltalk,
Modula-2, LISP, Forth, Perl, and more.  The OS/2 Tools Guide on
ftp-os2 (pub/os2/all/info/tinf26.zoo) contains information on these
and more.

[Vendors, ftp sites, phone numbers, prices?]

	Pascal: Microway ($595), JPI ($180)
	Modula-2: JPI ($180), Stonybrook
	Fortran: Microway ($595), Watcom
	Cobol: IBM Cobol/2
	Smalltalk: Digital Smalltalk/PM V, Parc Place Smalltalk
	Perl 4.0.10: ftp-os2
	LISP: ftp-os2
	XScheme: ftp-os2
	J: ftp-os2

(1.6)	Which of these compilers can be used to generate PM apps?

IBM C Set/2 can generate PM apps.  Workset/2 includes many sample
programs and the complete on-line reference.

GNU C/C++ 2.1 can generate PM apps, and includes a sample program that
does it.  emx/gcc can too, with some limitations (what are they?).

Most commercial C and C++ compilers can.  WATCOM C and FORTRAN and all
of JPI's can, too.  You will probably want the IBM Developer's
Toolkit, or similar documentation, however.

(1.7)	What is REXX?  How do I write and run a REXX program?

REXX is the IBM SAA (Systems Application Architecture) standard,
user-friendly programming language.  It is available for IBM
mainframes, Unix, the Amiga, DOS (Mansfield's Professional REXX),
Windows, and many other platforms.  It has been a part of standard
OS/2 since Version 1.3.  Programs written in REXX that do not use
system-specific libraries are fully portable.

OS/2 2.0 comes with an online REXX reference, and printed REXX
documentation is available (Mike Cowlinshaw's REXX book, IBM's twin
guides).  The Usenet group comp.lang.rexx discusses REXX programming.

(1.8)	What debuggers are available for OS/2?

IPMD, a PM-based debugger, ships with C Set/2.  It is capable of
source- and assembly-level debugging multithreaded 16 bit and 32 bit
OS/2 applications

emx comes with gdb, the GNU debugger.  

There are also several commercial debuggers on the market.  WATCOM C
and FORTRAN come with WVIDEO, a full-screen source or assembly lever
debugger that handles multithreaded 16 and 32 bit OS/2 programs.
Multiscope, others?

(1.9)	Where can I get documentation on the OBJ/LIB/EXE format used
	by OS/2 2.0? 

The .EXE format was described briefly in PC Magazine, Vol 11 No. 12
(June 30, 1992?); it was also described in a 1988 issue.

(1.10)*	Please summarize this information, and tell me what I need to
	do OS/2 development.

(1.11)  GCC/2 crashes with a trap when I try to compile a program.
	Why?

Because you didn't read the README or INSTALL files, probably.  There
are three general reasons GCC/2 will crash:

	1.  You did not set up the environment variables in CONFIG.SYS
	properly.  Read doc/INSTALL for instructions.

	2.  Some program that gcc expects to be in the PATH is not;
	unfortunately, gcc crashes instead of just printing an error
	message.  You may forgotten to install something, or your PATH
	may be wrong; see above.  Giving gcc the -v option will cause
	it to print each command line as it executes it; this will
	tell you which program is missing.

	3.  You are trying to get gcc to link your program for you.
	It cannot because ld does not exist, and so it crashes (see
	item 2).  You must specify -c, -E, or -S on every invokation
	of gcc, and then use LINK386.EXE to create an executable.  See
	the sample makefiles for an example of how to do this.

2.  Tools, Toolkits, Accessories
----------------------------------------------------------------------

(2.1)	What programming editors are available for OS/2?

OS/2 2.0 comes with the Enhanced Editor (EPM).  

GNU Emacs 18.58 is available.  It requires you to have emx installed
on your machine, but it comes with all the emx files you will need.
Emacs is available on ftp-os2 in /pub/os2/2.0/gnu/emacs.  (If you want
to recompile emacs, you will need the full emx distribution; see
question 1.2.)

Several public-domain vi clones are available, including elvis, Stevie
and levee.  The MKS Toolkit also includes vi.

Many other text editors are available.  

	Epsilon, by Luguru, (412) 421-5678.  DOS upgrade to OS/2 is
		$90.  This is a character based editor, not a PM app.

	QEDIT, Brief, KEDIT, others? [Vendors, phone numbers, prices?]

(2.2)	What programming tools/toolkits/accessories are available for OS/2?

The IBM Programmer's Toolkit, included in Workset/2, includes many
tools.

Borland will soon release ObjectVision for OS/2.  [Details?]

The MKS Toolkit, available from MKS ($349 USD, 800-265-2797 or
inquiry@mks.com), has over 160 Unix tools, including Korn shell, tar,
vi, awk, grep, tail, cpio, and so forth.  It also contains a Lex and
Yacc capable of generating C, C++, and Turbo Pascal code.

There is a product called ARGO/UX which provides a BSD environment for
OS/2.  [details?]

(2.3)	What GNU tools are available and where can I find them?

OS/2 1.x versions of most of the standard GNU utilties are available
on various OS/2 ftp sites, and they will work under OS/2 2.0.  Either
gcc or emx/gcc should be able to compile 2.0-specific versions of any
of them; if you port any, please announce it.  emx also comes with a
collection of utilities that are necessary or useful to use it.

(2.4)	Is a socket library available?  How can I use it?

IBM's TCP/IP 1.2.1 ($200, part #02G6968) includes an optional
Programmer's Toolkit ($500, part #02G6973).  It includes a socket
library, and support for Sun RPC, NCS RPC, and a limited Kerberos
capability.  It requires IBM C Set/2 or another compiler that
understands 16-bit code.

FTP Software, Inc., has an OS/2 version of its TCP/TCP product.  They
can be reached at (617) 246-0900 or info@ftp.com.

Walt Corey, KZ1F, is porting KA9Q to OS/2 and PM. The current version
of his code is available for ftp from giskard.uthscsa.edu. This is
still a work in progress, with rough edges here and there, and in
particular there's no Ethernet (or anything but async serial, i.e.
SLIP, PPP, and KISS) support yet, though that's high on the priority
list. You can email Walt at kz1f@giskard.uthscsa.edu.

If you have the IBM TCP/IP 1.2 base package and IBM C Set/2, you can
use the TCPIPDLL.DLL directly.  A 32 bit socket library interface to
do this for you will be available shortly.  It will also be possible
to call TCP/IP functions from programs generated with gcc.  (Yes, yes,
I know I've been promising this for a while.  I apologize for the
delay; be patient.)

3.  Programming, Porting
----------------------------------------------------------------------

(3.1)	How can I recompile public domain/shareware source code for OS/2?

Most publicly available OS/2 programs come with binaries (since there
is currently only one OS/2 architecture).  If you are porting source
code from another system (for example, Unix), you will first need to
acquire a compiler.  See section 1 for information on compilers; in
particular, note that the GNU C compiler is available.

You should realize that many publicly available programs have already
been ported to OS/2.  Check the many FTP sites carrying OS/2 programs
before you reinvent any wheels (the OS/2 User's FAQ contains
information on FTP site).

(3.2)	How can I port my DOS program to OS/2?
(3.3)	How can I port my Windows program to OS/2?

To the first approximation, you don't have to --- OS/2 2.0's DOS
support is excellent, and your DOS program will probably just work;
similarly, OS/2 2.0 supports Windows 3.0 (and soon 3.1) programs.  See
the OS/2 User's FAQ for details.

IBM Workset/2 includes Mirrors, a toolkit designed to help port
Windows applications to OS/2.  [Details?]

[But this doesn't answer the question...]

(3.4)	Is OS/2 suitable for real time programs?
(3.5)	How do I write an OS/2 device driver?

There's a book called "Writing OS/2 2.0 Device Drivers in C" from Van
Nostrand-Reinhold, see question 4.5.  There's also IBM's flood of
printed material.

(3.6)	How can I simulate (Unix feature) under OS/2?
	(a) fork
	(b) fork/exec
	(c) select

In general, you can't.  select() depends heavily on the fact that all
sources and sinks of data originate in the filesystem and are
identified by a coherent set of file descriptors; these assumptions
are not true under OS/2.  For (almost) any particular kind of data
source/sink (files, sockets, pipes) you can achieve most of select()'s
semantics.  A decent solution to this problem requires a C library
that maintains its own array of file descriptors and information on
each one such that it can dispatch to the appropriate module in
response to library calls.  The C libraries delivered with gcc and
emx/gcc will have such functionality in the (possibly near) future,
but don't yet.

	(d) job control

(3.7)	How does programming PM compare to programming X?

Many people have said "PM is much cleaner."  Until I hear from someone
I trust with extensive experience with both (I only know X), however,
this FAQ will take no position.

(3.8)	Why doesn't printf() produce output when I expect it to?

For historical reasons, most Unix C libraries' stdio default to using
line buffered streams, whereas most DOS and OS/2 C libraries' stdio
default to using fully buffered streams.  ANSI C species that standard
output should be line buffered when connected to an interactive
device, but not all libraries are ANSI compliant.  You can control the
buffering algorithm used for a particular stream with the setvbuf()
function.

If you didn't understand that paragraph, read on.

printf() is part of the Standard I/O (stdio) library, which uses
buffered streams for file IO.  ANSI C specifies three algorithms for
deciding when to flush the buffer (i.e. when to print buffered data to
the file):

	o not buffered.  Data is flushed to the file as soon as
	possible, usually immediately after being received.
	
	o line buffered.  Data is flushed to the file when a newline
	is received (and the newline is also flushed).

	o fully buffered.  Data is flushed to the file when the buffer
	is full.

Buffered data is always flushed when the stream is closed or when
fflush() is called.  Since standard output is flushed when main()
exits, all data printed with printf() will appear at that time, if it
has not already.  However, ANSI C does not require that a stream be
flushed when scanf() is called on it.  Therefore, if you print to a
fully buffered stream and then request input on it, it is likely that
the input will be read before the printed data appears.

You can control the buffering algorithm used for a particular stream
with the setvbuf() function.  For example, the statement
setvbuf(stdout, NULL, _IOLBF, BUFSIZ) sets standard output to be
line-buffered, which is what most Unix programmers expect.  Any decent
C reference will cover all of this material.

The gcc 2.1 library will have a line-buffered stdout by default in a
future release.

4.  Documentation, Help
----------------------------------------------------------------------

(4.1)	Where can I get information on OS/2 APIs and programming?

The IBM Programmer's Toolkit, included in Workset/2, includes a
complete on-line syscall reference.

You can order the seventeen volume IBM OS/2 Technical Library
(possibly at a discount, see question 1.2) and/or order various
volumes individually; the file pub/os2/2.0/info/os2pubs.txt lists all
(many?) of the IBM OS/2-related reference manuals, as of May 20, 1992,
along with ordering information.

See question 4.5 for information on printed reference books.

(4.2)	Where can I get sample code?

There is a lot of sample code included in the IBM Toolkit, and 4
sample programs (with source) included with C Set/2.  GNU C/C++, from
ftp-os2, includes a sample C, C++, and C++ PM program.  The OS/2
Redbooks (see question 4.5) also have some sample code.

(4.3)	Are there any OS/2 programming classes or seminars?

Yes.  Call IBM at either 1-800-3-IBM-OS2 in U.S. (or the PS/2 Help
Center).  Local IBM branches frequently hold OS/2 classes and
seminars.  I haven't seen third party efforts in this regard, but I
know they exist.

See pub/os2/2.0/info/ivleague.txt on ftp-os2 for a list of third-party
support organizations.

(4.4)	What are good reference books for programming in OS/2 and PM?

Van Nostrand Reinhold publishes a number of books on OS/2 2.0.  Those
that relate to programming are:

INTEGRATING APPLICATIONS WITH OS/2 2.0
By William H. Zack
0-422-01234-9

CLIENT SERVER PROGRAMMING WITH OS/2 2.0
By Robert Orfali and Daniel Harkey, IBM Corporation
0-422-01219-5

WRITING OS/2 2.0 DEVICE DRIVERS IN C
By Steven J. Mastrianni; Foreword by John Soyring, IBM Corporation
0-442-01141-5

OS/2 2.0 PRESENTATION MANAGER GPI: A Programming Guide to Text,
	Graphics, And Printing
By Graham C.E. Winn, IBM Corporation
0-442-00739-6

THE COBOL PRESENTATION MANAGER PROGRAMMING GUIDE
By David M. Dill, Consultant
0-442-01293-4

LEARNING TO PROGRAM OS/2 2.0 PRESENTATION MANAGER BY EXAMPLE: Putting
	the Pieces Together
By Stephen Knight, IBM Corportaion
0-442-01292-6

Also see the information about redbooks in answer 4.5.

(4.5)	What are the OS/2 redbooks, and how do I get them?

IBM publishes so-called "redbooks" on many products, including OS/2
2.0.  They seem to be a combination of power-user's guides and design
information that may be of use to both users and programmers [I
haven't received my copies yet, so I cannot say for sure.]  These are
usually intended only for special IBM customers and contain
documentation that is generally unavailable anywhere else.  You can
order these books directly from IBM (see below).  All of the following
names are implicitly preceeded by "OS/2 Version 2.0."

 Volume 1: Control Program: GG24-3730, $4.15
   
   Technical information on Memory Management, Task Mangement,
   Support, Installation Considerations, Hardware Considerations, Boot
   Manager, National Language Considerations, Intel 386 architecture,
   Channel Architecture and SCSI.  Documents config.sys.
   
 Volume 2: DOS and Windows Environment, GG24-3731, $6.20
   
   MVDM,8086 Emulation,MVDM DOS emulation, Device Drivers, Memory
   Extender Support, Installing and Migrating Applications, Windows
   Applications, DPMI, Running DOS apps,DOS settings, VMB.
   
 Volume 3:  PM and Workplace Shell GG24-3732, $3.65

   Available now, but I don't know precisely what's in it.   
   
 Volume 4: Application Development GG24-3774, $5.25
   
   Technical programming info (includes list in C) Overview,
   Object-Oriented Apps, PM application model, flat memory model,
   building PM app, Workplace AOAShell and System Object Model, Direct
   Manipulation (Drag/drop), PM resources, Multitasking
   Considerations, SAA CUA considerations, App Migration, Mixing 16
   and 32 bit application modules, compiling and link editing (SOM),
   Adding Online Help, Problem Determination, Managing Development,
   Naming conventions.
   
 Volume 5: Print Subsystem, GG24-3775, $5.20
   
   Not Available yet.

The special part number GBOF-2254 is for all currently available
volumes (presently 1-4).

ORDERING INFORMATION:

The OS/2 2.0 Redbooks are available from IBM's TeleServices customer
support number.  The number is 1-800-7654-IBM (1-800-765-4426).  You
can pay by credit card or mail in a check after calling.  The order
will take about 2 weeks but can be sped up by paying for faster
shipping.

You can also order the redbooks from your local IBM Branch Office
library.  Some possibly useful phone numbers are included here.

	IBM Central Library, Los Angeles CA: (213) 621-6710
		P.O. Box 60737
		Los Angeles, CA 90060
	Canada: (800) 465-1234, ext 4205 ($33.52)
	UK: (0256) 478166, (#36.51, credit cards accepted)
	Australia (Victoria): 698-1234 ($46.80 A)
   		IBM Australia
             	The Library
             	211 Sturt Street
             	South Melbourne, 3205
             	Att: Kate Seeley
	Denmark: 33 32 40 55 (dkk 310)

5.  Miscellaneous
----------------------------------------------------------------------

(5.1)	What is available for multimedia programming under OS/2?

The OS/2 2.0 Multimedia package is now available.  Call the
IBM Multimedia office at (800) 426-9402 ext. 150.

(5.2)	What is available for AI/neural net programming under OS/2?

LISP and XScheme are available from hobbes.  There are also some
AI/neural net tools listed in tinf26.zoo.
--
Barry Jaspan, bjaspan@mit.edu